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SCOPE 


This manual describes the 8080/280 dependent aspects of the C 
programming environment provided by Whitesmiths, Ltd. In addition, 
it documents all of the utilities necessary for building new 
programs, Section I introduces the conventions and describes the 
format used by the Idris assembler. Section II succinctly describes 
the programming utilities of Idris, which also serve as cross sup- 
port utilities for other host machines. Each subsection of Section 
III describes the library functions that interface the portable C 
library to Idris, CP/M (CDOS), or ISIS-II, and Section IV describes 
the runtime routines called upon by code produced by the 8080/280 C 
compiler. 


Information on the C language and the portable library may be found 
in the C Programmers' Manual, while information peculiar to other 
machines supported by Whitesmiths, Ltd. is given in other C Inter- 
face Manuals. 


THIS MANUAL IS PROVIDED WITH SEVERAL SOFTWARE PACKAGES, SOME OF 
WHICH USE ONLY A SUBSET OF THE FACILITIES DOCUMENTED. THE PRESENCE 
OF A MANUAL PAGE HERE DOES NOT IMPLY THAT THE CORRESPONDING SOFTWARE 
IS ALSO SUPPLIED. 
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I. The A-Matural Language 
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A-Natural in brief 


As.80 I. The A-Natural Language As.80 


NAHE 
As.80 - Introduction to A-Natural 


FUNCTION 

A-Natural, otherwise known as As.80, is a narrative assembly language for 
use with the Intel 8080, Intel 8085, or Zilog 2/80 computers. It features 
à uniform naming convention for registers, a concise operator notation for 
most machine instructions, and formatting rules that make logical 
groupings very visible. Nevertheless, the language makes available to the 
programmer the full power of the underlying instruction set, and is care- 
ful not to generate unexpected side effects, such as altering unnamed 
registers. 


The contrast between A-Natural and assembly language oan be made by the 
code sequence for subtracting two 16-bit integers, at memory location X 
and at À + de: 

a= *(be = &X) - "(hl = 4 + de) -> #be = *(be + 1) -^ "(hl + 1) -> *be 


or, in assembler: 


LXI B,X INX B 
LDAX B LDAX B 
LXI H,4 INX H 
DAD D SBB M 
SUB M STAX B 
STAX B 


Note that register a is explicitly named, that all references to hl use 
the same name (not H, M or implicit), that all data moves are called out 
with the assigning operators "=" and "->", and that a few operators are 
used to express addressing modes ("#", "&") and arithmetic ("-", "-^"). 


To read a line of A-Natural requires the repeated application of a few 
rules: 


1) Reading left to right, locate the first binary operator, in this case 
tan 


2) If the operand to the left is not a simple term, evaluate the subex- 
pression. In this case, the operand is just a. 


3) If the operand to the right is not a simple term, evaluate the subex- 
pression. Here *(be = &X) requires code production for be = &X, 
which is "LXI B,X", and then reduces to #bc. 


4) Produce code for the binary operator using the two reduced operands, 
here a = "bo. 


5) Keep the left operand, discard the rest, and repeat. The line then 
becomes 


a - #(nl = 4 + de) -> #be = *(bo + 1) -^ *(hl + 1) -> *bc 


As.B0 -2- 4.80 


Under this scheme, all binary operators have the same precedence, so ex- 
pressions read striotly left to right, except where order is explicitly 
modified by parentheses. 


The use of A-Natural is described by the following subsections: 

45.80 - you're looking at it. 

Syntax - how to form identifiers, constants, expressions, etc. 

Defining - giving values to symbols and expressions, generating constants. 
Moves - the 8080 registers and basic data moves. 

Arithmetic - manipulation of bytes and addresses, and fancier moves. 
Control - flow of control and process control. 


Techniques - how to deal with integers and addresses, how to mix with C 
eode. d 


Summary - the language in a nutshell. 


EIAMPLE 
Here is the complete text of a library module in A-Natural: 


imul 

copyright (c) 1979 by Whitesmiths, Ltd. 
mul int into int 

stack: P, bo, hl, po, R, L 


P=0 
while (R) 
if (R & 1) 
P =L 
Loc 
R =» 1 
L=P 


NNN NAN NSS NS 


public c,imul 
R := 8L t= 10 c.imul: 
sp <= hl <= be <= (hl = 0) 


a= "(nl = R[1] + sp) | *(hl - 1) jz .3 
a = hl <*> -1 jno .2 

(hl = L + sp) 

hl <= sp + bo => sp 


"(hl = L + sp) + a -> *hl = "(hl + 1) «^ a -> "hl 
*(hl = R[1] + sp) <-> -1 -> *hi 
a = "(n) - 1) «^» -1 -> "hl 


23- 


be <= sp ->* (hl = L[-2] + s 
jmp c.lret " 


Syntax I. The A-Hatural Language Syntax 


NAME 
Syntax - rules for writing A-Natural 


FUNCTION 
At the lowest level, an A-Natural program is represented as a text file, 
consisting of lines each terminated by a semicolon ';', a newline '\n', or 
a comment. A comment consists of all characters between a '/' and the 
next newline, inclusive. 


Text lines are broken into tokens, strings of characters possibly 
separated by whitespace. Whitespace consists of one or more non-printing 
characters, such as blank or tab; its sole effect is to delimit tokens 
that might otherwise be merged. Tokens take several forms: 


An identifier - consists of a letter, dot '.', or underscore ' ', followed 
by zero or more letters, dots, underscores, or digits. Uppercase 
letters are distinct from lowercase letters; no more than nine 
characters are significant in comparing identifiers. More severe 
restrictions may be placed on identifiers by the world outside the 
translator. There are also a number of identifiers reserved as key- 


words: 

. em de jmp public rsti 
„data enc di jne re rst2 
etext ene e jnz ret rstj 
a enz ei ip rm rst 
af ep h ipe rnc rst5 
b cpe hl jpo rnz rstó 
be epo hlt jz rp rst] 
e ez in 1 rpe rz 
call d je nop rpo sp 
oc daa jn out rsto ste 


A numeric constant - consists of a decimal digit, followed by zero or more 
letters and digits. If the leading characters are "Ox" or "OX", the 
constant is a hexadecimal literal and may contain the ietters 'a' 
through 'f', in either case, to represent the digit values 10 through 
15, respectively. Otherwise a leading '0' implies an octal literal, 
which nevertheless may contain the digits '8' and '9', A nonzero 
leading digit implies a decimal literal. Numbers are represented to 
16 bits of precision; overflow is not diagnosed. 


A character constant - consists of a single quote, followed by zero or 
more character literals, followed by a second single quote. A 
character literal consists of a) any character except '\', newline, 
or single quote, the value being the ASCII representation of that 
character; b) a '\' followed by any character except newline, the 
value being the ASCII representation of that character, except that 
characters in the sequence <tb', 't', 'v', !f', tnt, Met, *(*, tnt, 
!)', '^'» in either case have the ASCII values for the corresponding 
members of the sequence <backspace, horizontal tab, vertical tab, 
form feed, newline, carriage return, '(', '|', !']', '^'»; orc) a 
'A' followed by one to three decimal digits, the value being the oc- 
tal number represented by those digits. A newline is never permitted 
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inside quotes. The value of the constant is an integer base 256, 
whose digits are the character literal values. Only the last two 
Such digits are retained. Overflow is not diagnosed. 


A string constant - is just like a character constant, except that double 
quotes '"' are used to delimit the string. A string is shorthand for 
a series of byte constants, the values being the character literals 
in the stríng. 


Punctuation - consists of predefined strings of one to three characters. 
The complete set of punctuation for A-Natural is: 


! + -^ I [ 
& 4 i <-> 1 
( - <z * 
) -> <> l 
* ->^ <> 


The longest possible punctuation string is matched, so that "=!", for 
example, is recognized as "=<!" always, and never as '-' followed by 
"I'. The operators "I" and "|" are equivalent. 


Other characters - such as '@' or '\' alone, are illegal outside of 
character or string constants, and are diagnosed. 


Nothing else is a token in A-Natural. 


For those who love Backus-Naur Form, A-Natural can be succinctly expressed 
by the productions: 


program :- «NULL» 

| program line 
line t= <NULL> EOL 
| term EOL 
l STRING EOL 
| expr EOL 
| IDENT : line 
expr 32 term BINOP term 
| expr BINOP term 
term := NUMBER 
l IDENT 
|  UNOP term 
J IDENT 
| IDENT 
| {expr} 
| term [ expr ] 


term 
expr 


where the following definitions obtain: 


<NULL> is nothing 
EOL is a line terminator, e.g. ';' or '\n' 

STRING is a string constant 

BINOP is one of several binary operators to be described 
NUMBER is a numeric constant or a character constant 


IDENT is an identifier 
UNOP is one of several unary operators to be described 


In plain English, this says that a program is a concatenation of zero or 
more lines, each of which may be empty, or contain a term, or contain a 
string constant, or contain an expression. A line may be preceded by zero 
or more labels, where a label is an identifier followed by a colon. 


An expression is a sequence of two or more terms, separated by binary 
operators. Expressions read left to right. A term, at its simplest, con- 
sists of just a numeric constant, a character constant, or an identifier. 
It may also consist, however, of a definition, which is an identifier fol- 
lowed by ":-" and an expression, or it may consist of an expression inside 
parentheses. It may be preceded by zero or more labels and/or unary 
operators; it may be followed by zero or more subscripts, each enclosed 
in brackets. 


This seeming generality is circumscribed by a few important semantic 
restrictions. These restrictions are discussed as each of the interesting 
productions are visited in more detail. 


BUGS 
m should be a reserved identifier. 


Defining I. The A-Matural Language Defining 


MAME 
Defining - defining symbols, data, and code 


FUNCTION 
The goal of A-Natural is to produce a module, of assembler statements or 
relocatable binary, that defines certain globally known symbols, that 
specifies the initial content of data areas, and that expresses the se- 
quences of instructions that form each function body. An important sub- 
goal is to define the value and attributes of terms and internally used 
symbols. 


Symbols and terms stand for data items to be manipulated; each can be 
viewed as a recipe for locating the data in question. There are a number 
of predefined identifiers for talking about registers, while numerical 
values are represented by numeric and character constants, as well as 
Strings. All memory addresses and references derive from a few sources. 


There is a predefined symbol .text which stands for the next location to 
generate code into in the program text (read only) section of memory. The 
symbol .data stands for the next location to generate code into in the 
data (writeable) section of memory. A third symbol, written simply ., is 
the next location that A-Natural will generate code into, either .text or 
»data. 


An as yet undefined identifier may appear in a defining statement of the 
form: 


x:23 
Henceforth, any reference to x will be taken as a reference to the literal 
number 3, a one-byte constant. The right side of the defining operator 
"iz" must be an expression that evaluates to a number, a memory address, 
or a memory reference. 
The usual source of memory references is ., as int 


This defines M as the contents of the next byte (or two bytes) of memory. 
So often does this occur that a special label notation is provided: 


M: 


has the same effect, of defining M as ., but is shorter to write and may 
be followed by additional labels or by à term. 


If it is necessary to talk about a memory address proper, instead of the 
contents of memory, the "address of" operator &M converts a memory 
reference M to a two-byte constant whose value is the address of M. 
Similarly, &3 converts the one-byte constant to two-bytes, while &&3 
leaves &3 unchanged. 


To convert a two-byte constant to a memory reference, the unary "indirect 
on" operator "*" is used. Thus, *&M is the same as M and *&3 is the 
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memory location at absolute address 3. The "#" operator is also used in 

conjunction with certain two-byte registers to specify register indirect 

reference. 

Other unary operators are "+", "-", and "I", which modify the value of one 

or two-byte absolute constants. The value is left alone by "+", negated 

by "=", and ones complemented by "I". The operator public makes its 

operand, which must be a symbol, known across all files at load time: 
public x 

This term does nothing but declare x to be globally known. 

The value of a term may be modified by a constant offset by using the sub- 

Script notation M[5]. This term refers to the location five bytes up from 

M, while 3[5] is the one-byte constant 8, and &3[5] is the two-byte ab- 

solute address 8. 


Code generation uses this notation plus a few additional concepts. A one- 
byte constant standing alone generates one byte of code having that value: 


N: 0 
Byte location N is initialized to zero. 
To generate a two-byte constant: 


list: £0 


list: &nead 


where head is presumably another label. By special dispensation, the & 
can be omitted in this context, 


Strings may be used to specify a sequence of bytes. For instance: 
"help\n\o" 
is the same as 
Th's 'e'; '1l'; 'p'; "a' 0 
only much easier to type. 
Concatenation is the only operation permitted on strings. The comma 
operator permits one-byte constants, two-byte absolute constants, and 


strings to be concatenated to form longer strings, as in: 


"help", "\n", 0 
tht, tet, "Lp\n\o# 


both of which are equivalent to the string above. 
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One last unary operator is a peculiar one called "literal". The term -àM 
causes a two-byte literal whose value is the address of M to be memorized 
in a table. At the end of source input, code generation reverts to .text 
and the table is emitted; identical literals are merged as much as 
possible. The value of the term -&M is a memory reference to that literal 
to be emitted. This permits relocatable addresses to be manipulated a 
byte at a time by references to (:4M)[0] and (-MM)[1]. 
String literals may also be generated, by writing lines like 
hl = &="help\n\0" => sp 
which is a convenient way of defining a literal string and pushing its 
address on the stack all at once, As another example, a long constant can 
be written either as a string of four bytes or two two-byte constants, as: 
hl s &s(&-1, &4) => sp 
to get a pointer to a long -l on the stack. 


To switch from generating code into .text (whioh A-Natural always starts 
out doing) to generating data into „data: 


+ t= .data 
and to switch back: 
. ta text 
and to reserve space, as for an array: 
+ t= .[50] / reserve 50 bytes 
Note that . is the only identifier that may be redefined, that its 
redefinition must be relative to .text or .data, and that . cannot be 


backed up over code already produced. 


All other code generation is specified by binary operators between terms, 
as described in the As.80 subsection of this manual. Thus, 


X op Y op Z 
is shorthand for 
X op Y; X op Z / X a simple term 


and leads to eode production for 1) tne term X, 2) the term Y, 3) X op Y, 
4) the term 2, and 5) X op Z. 


Later sections of this manual describe the defined binary operators, the 
combinations of terms they accept, and the actions performed. 


Moves I. The A-Hatural Language Moves 


NAME 
Moves - how to move data about 


FUNCTION 


The Intel 8080 is a computer that deals in 8-bit bytes and 16-bit addres- 
ses (words) using twos-complement arithmetic. All instruction and data 
bytes are fetched from the same 65,536 byte address space, which may be a 
mixture of ROM (for code and tables) and RAM (for stack and data). Words 
are stored less significant byte first. Input/output is a byte at a time 
from a separate 256-port address space. 


Seven byte registers can participate in byte operations. These are called 
a (which frequently serves as a byte accumulator), b, c, d, e, h and l. 
Another byte register, called f, holds flags that are set or tested as a 
side effect of some instructions. These flags are, in order of descending 
significance: 


f] (S) - is made to match the sign of the result of most byte arithmetic 
instructions. 


f6 (Z) - is set if the result is zero for most byte arithmetic instruc- 
tions. 


f5 (0) - is always 0. 


fh (AC) - is set on a carry from bit 3 to bit 4 on most byte arithmetic 
instructions. 


f3 (0) - is always 0. 


f2 (P) - is set if the result has an even number of one bits on most byte 
arithemtic instructions. [N.B. This flag doubles as an overflow in- 
dicator on the 2/80, the only known flaw in its upward compatibility 
with the 8080.] 


fi (1) - is always 1. 


fO (C) - is set on a carry from bit 7 of many byte arithemtic instruc- 
tions, is set on a carry from bit 15 on word adds, participates in 
byte rotations, and can be explicitly set or complemented. It is 
usually called the carry flag. 


Flag settings will be discussed with each instruction that uses them. 


These byte registers are combined in pairs to form four word registers, 
called af, bc, de, and hl. In each case, tne first register named holds 
the more significant byte. hl is most heavily used as a pointer ac- 
cumulator; af can only be pushed or popped. 


Another word register is sp, which is dedicated as a stack pointer. Only 
word quantities may be moved on or off the stack, although there is no re- 
quirement that sp contain an even address. A quantíty is pushed by 
decrementing sp by two, then using sp as the storage address of the less 
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significant byte; popping first uses sp as the source address, then adds 
two to sp. Thus sp always points at the last word pushed on the stack, 
i.e., the top of stack. 
The final word register is pc, which is dedicated as the program counter. 
At the start of each instruction po points to the opcode byte, which may 
be followed by a one-byte immediate operand or a two-byte address. A 
special class of instructions is used to modify po, and hence alter flow 
of control; these are called jumps, calls, returns, and resets. pe is 
not a reserved identifier in A-Natural. 
Any byte register may be copied to another, as in: 

ezb 
or equivalently, 

bore 
which copies b into c. Moreover, any operation that is permissible for b, 
C, d, e, h, and 1 is also permissible for the byte pointed at by hl, i.e., 
"hl. Thus, 

az hl ec 


calls for a to be loaded with a copy of the byte pointed at by hl, then 
copied into c. No flags are affected by these byte moves. 


Note that the eight special cases 
be bs cse... "hl = *hl 


Should be avoided, because the instruction either does nothing or halts 
the computer ("hl = *hl). A one-byte no operation is best coded as 


nop 
while a halt is best written 


hlt 


The identifiers nop and hlt are simply defined as small numbers having the 
proper secret values; since stating a number alone causes a byte with 
that value to be generated inline, the proper instructions are produced. 


It is possible to assign a byte constant to any byte register, or *hl, by 
writing 


13 
= 0200 


The first line copies a decimal 13 into d, the second an octal 200 into 
the byte pointed at by hl. 
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Register a can participate in several other moves: 


a -> "be 
a -> "de 


Here, M stands for an arbitrary memory address, of the byte to be loaded 
or stored, 


Word values may be assigned to most of the word registers: 


be = &1024 
de = &M 
hl = 3 
sp = &stack 


The third line is simply shorthand for 


while the fourth is very rarely used, since sp ís usually setup only once 
per program. A much more frequently used assignment is: 


sp = hl 


after computing a modified version of sp in hl. Note that af may not be 
assigned to; assigning to po occurs in the guise of jumps, calls, etc. 


It is also permissible to load and store hl directly from memory: 
nln:X-»Y 


This copies the word in memory at X to memory at Y, using hl, and should 
not be confused with the loading of an immediate value as shown above. 


Finally, it is possible to copy words arbitrarily among be, de, and hl, by 
writing lines like: 


bo 
hl 


de 
be 


These operations are actually performed a byte at a time, and so may be 
viewed either as two byte instructions or as shorthand for lines like: 


e 
l 


ej b 


d 
ejhzb 


The difference is rarely significant. 
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Arithmetic I. The A-Hatural Language Arithmetic 


NAME 
Arithmetic - manipulating data on the 8080 


FUNCTION 

The 8080 manipulates data as eight-bit bytes and, to a much lesser extent, 
as 16-bit words. Arithmetic in the usual sense of the term is restricted 
to addition and subtraction; there are no multiply or divide instruc- 
tions. But there are also a number of logical operations, as well as 
rotates of various flavors, that make possible multiple precision computa- 
tions and more elaborate operations. Hence all this stuff is lumped 
together. 


It is easy to add or subtract one from any byte register or "hl: 


These operations set all but the carry flag. On the other hand, the word 
increment and decrement operations: 


be + 1, de + 1, hl + 1, sp 1 
bo ~ 1, de = 1, hl-1, sp- 1 


affect no flags at all. Inorementing or decrementing sp is rarely useful, 
by the way. 


Any of the byte registers, *hl, or a byte constant may be added to a: 
a « o + 060 


Each addition affects all flags. Word addition may only occur from bo, 
de, or sp to hl: 


hl = 4 + sp -> be 


This is the best way to get sp + 4 into bo, using hl as a word ac- 
cumulator. Only the carry flag is affected. 


All other arithmetic in the 8080 involves a byte operand that is in a 
register, at "hl, or constant and a second byte operand in a, with the 
result left in a and all flags affected. The complete set of operations, 
ineluding the addition already discussed, is: 


a 


* add 
+^ "hl 


/ 

/ add with carry 

/ subtract 

/ subtract with borrow 
/ bitwise and 

/ bitwise exclusive or 
/ bitwise inclusive or 
/ compare 


oe ee ee) 
omi 


Adding a to a effectively doubles it, or shifts it left one place, at the 
same time moving the previous sign bit a7 into the carry flag. 
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Add with carry is the same as add, except that, if the carry flag is set 
at the start of the instruction, a one is added to a along with the right 
operand. 


Subtract adds the twos complement of the right operand to a, setting the 
carry flag if a "borrow" must be propagated to the next more significant 
byte. Subtract with borrow continues this chain, much like add with carry 
does for addition. 


The bitwise operators follow the standard truth tables: 


XY. XY XUI Ee 
00 0 0 o 
01 0 1 1 
13 1 0 1 
10 o 1 1 


These operations unconditionally clear the carry and AC flags. 


Note that a ] a or a & a leaves a unchanged, but sets the S and Z flags to 
reflect its value. Compare also leaves a unchanged, setting tne flags to 
reflect the effect of subtracting the right operand from a. 


The complement operator 


replaces a with íts ones complement, affecting no flags, while 
daa 


jiggers up the a register after an add to give the correct result for add- 
ing decimal numbers packed as two four-bit digits per word. This is the 
only instruction that makes sensible use of the AC flag; it sets all 
flags so that the decimal sum may be continued to more significant bytes. 


The a register may be rotated one place left or right with or without the 
carry flag being interposed between a7 and a0: 


a €» 1 / rotate left with carry 
a «^» -1 / rotate right with carry 
a C» 1 / left without carry 
a € -1 — / right without carry 


To manipulate the carry flag directly: 
ste / sets carry 
eme / complements carry 
ala / clears carry (but also affects other flags) 


Two other operators perform rotates after forcing carry to a known state: 
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a» 1 / set carry, rotate left 
a € -1 — / set carry, rotate right 
a <-> 1 / clear carry via ala, rotate left 
a <-> -1 / clear carry vía ala, rotate right 


The last is most frequently used to effect a right shíft with no sign 
propagation. All rotates affect the carry flag; if it does not par- 
ticipate in the shift, it is still set as if it did. Note that the "<->" 
operator curdles the flags, as a result of the ala. 

The 8080 has some peculiar instructions for more specialized moves, suoh 
as stack pushing and popping, and exchanges. Combined with some simple 
&rithmetic sequences, these give an additional set of fancier data moves. 
To push a word register onto the stack: 


sp <= bc — / or de, or hl, or af 
be => sp / or de, or hl, or af 


Either form has the same effect. Popping is the reverse notation: 


sp => be / or de, or hl, or af 
be <= sp 


It is also possible to exchange hl with the top stack word: 
hl <> "sp 

or: 
sp <> hl 


Note that it is *sp that is swapped with hl, not sp. The only other ex- 
change is 


nl <> de 
which may also be written either way around. 


Tne only way to load a word register from a computed address is to put the 
address in hl and pick up a byte at a time, as int 


e = "hl 
he1 
b = *hl 


This occurs so often that a special notation is used: 
be =^ hl 


where the ^ is a reminder that hl is upped by one as a side effect. Legal 
variations are: 
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be =^ hl, de «^ hl 
be ->° hl, de ->° hl 


The latter two cause word registers to be stored using hl as a memory 
pointer. 


Finally, the oft needed sequence: 
az "hl 
hl+1 

h = "hl 

lea 

which replaces hl with the word it points at, using a, can be written: 
hl =a* hl 


Again, the a and ^ warn that a is clobbered, and hl incremented. 


uos 
The only way to add one and set the carry flag is by the ruse: 


a + 0401 
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NAME 
Control - jumps and process control 


FUNCTION 
Control takes two forms in a computer, directing the sequence of opera- 
tions within a given process, and directing the interaction among proces- 
ses and their environment. The former is effeoted by conditional jumps, 
subroutine calls, and returns; the latter is usually implemented as a 
hodgepodge of peculiar instructions. In both cases, the 8080 is most 
typical. 


An unconditional transfer of control is called a jump, which can be writ- 
ten as a unary operator: 


jmp X 

which moves the address X into pc (jumps to X), or as a binary operator: 
a = 0 jmp M 

The latter sequence clears a, then jumps to M. 


There are also eight conditional jumps, that jump only if the appropriate 
flag state obtains, There are: 


OPERATOR JUMPS IF 
jnz X Z=: 0 
jz X Z=: 1 
jac X C a2 0 
jo X [E 
jpo X p? 0 
jpe X P 1 
dp Xx S 0 
jm x S=: 1 


To transfer to a subroutine, the call instruction 
call X 

pushes pe on the stack, then jumps to X. This permits a return with 
ret 


to get back to the calling sequence by popping pc from the stack. Calls, 
like jumps, are treated as operators, while returns are numbers. 


The 8080 also has a full complement of conditional calls and returns, al- 
though they are rarely used: 


cnz X rnz 


ezX rz 
enc X rnc 
ecX re 
epoX rpo 
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epe X rpe 
ep X Tp 
em X rm 


Finally, it is possible to jump to a computed address with 
jmp *hl 
which copies hl into po. 
A more specialized way to oall a function is with a restart instruction: 
rato; rati; ...; rst7 
The general form rstn pushes pc on the stack, then jumps to absolute loca- 
tion 8*n, i.e., to location 0, 8, 16, 24, etc. Restarts are usually 
reserved for communicating with system functions, In fact, when an inter- 
rupt occurs, the 8080 usually behaves as if an rstn instruction were in- 
jected into the code sequence, with n supplied by the interrupting hard- 
ware, : 
Interrupts can be enabled (allowed to happen) by executing 
ei 
and disabled with 
di 


If interrupts were disabled and ei is encountered, the instruction fol- 
lowing ei is executed before interrupts are actually enabled. 


Up to 256 logical ports may be addressed by the 8080 for performing byte 
at a time input/output. There 1s no requirement that a port be actually 
present, or that an output port be associated in any way with an input 
port having the same number. 
To read data: 

in; n 
copies whatever input port n is sending into the a register, while 


out; n 


presents the oontents of a and the port address n to the outside world. 
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MAME 
Techniques - 8080 for grownups 


FUNCTION 
Just knowing the instruction set of the Intel 8080 is not enough to 
program it properly because a) the set is primitive, b) it is incomplete, 
and hence c) the most commonplace of operations are often nontrivial and 
unobvious. This section describes a number of techniques for coding 
maturely in such an immature environment. 


With rare exception, byte (or any other) operations require the use of a 
&s an accumulator; hence af should be viewed as extremely volatile. 
Returning byte values in a, for instance, is often suboptimal because a is 


frequently needed just to get back from a function! More important is to 
know: 


1) What can be loaded into a - (b, c, d, e, h, 1, *hl, #, *bc, *de, M) 
2) What can be added to a - (b, c, d, e, h, 1, #hl, 4) 

where # is any one-byte constant and M is a memory reference. Fore 
tunately, whatever can be loaded into a can also be stored from a, except 
of course a constant; and what can be added to a can also be subtracted, 
anded, etc. 


Thus, the most general technique for performing an operation <op> between 
bytes is: 


1) Set up destination address in bc 
2) Set up source address in hl 
3) Write "a = "bo «op? "hl -> bo", 


Naturally, steps (1) or (2) can be omitted if the operand happens to be 
already within reach. 


To get operands in reaoh requires address arithmetic, which usually in- 
volves hl as a pointer accumulator. If an operand is on the stack, 


hl = D + sp 
allows the data at displacement D off of sp (also written D(sp)) to be 
addressed as *hl. The C language uses de as a "frame pointer", so as not 
to have to keep close tabs on the state of sp. Thus, arguments and 
automatic variables are addressed as D(de), where D runs from ! up for 
arguments and from -7 down for autos. The sequence 

be = (hl = 4 + de) 
clearly loads be with the address of the first argument. 


Often it is necessary to trace down a chain of pointers to get to the 
operand, This is known variously as indirect addressing or dereferencing. 
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For this, the two complex moves "s^" and "-a^" frequently pay off. If, 
for instance, the first argument is a pointer to the operand of interest: 

bo =° (hl = 4 + de) / operand now at *bo 
or: 
hl za" (hl = 4 +de) / operand now at *hl 


Further modification, such as adding a constant offset into an array or 
structure, usually requires both be and hl: 


hl = 6 + be -> bo / for be + 6 


hl + (be = 4) / for hl + 4 


If the offset to be added is smaller than those shown, however, it is 
shorter and faster to write: 


bo + 14141 / for be + 3 
or: 

hl+t+1+1 / for hi +3 
and no other registers are needed. 


Testing invariably requires that the appropriate flag in f be set. For 
signed arithmetic, there are six possibilities: 


TO JUMP IF 


cope ee 


Note that all but the two equality comparisons give incorrect results if a 
and b differ by 128 or more, This is a hard error to avoid, unless the 
test can be converted to an unsigned comparison, shown below. 


To compare the byte at b against zero: 


TO JUMP IF CODE 
azblajmXx 
acblajpX 
a-blajzX 
azsbj|ajnzx 
&-at: b jnX 
a-a bipX 
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Unsigned tests are the same as signed, except that the carry flag is in- 
spected instead: 


CODE 

b je X 
b jno X 
b jz X 
b jnz X 
a jo X 
a jno X 


co»ppo 


These tests are correct for all values of a and b. The meaningful zero 
comparisons for unsigned collapse to equality and inequality, which are 
the same as above: 


TO JUMP IF CODE 
b asbla jzXx 
b asbj|ajnzX 


Multiple precision arithmetic, which frequently includes even two-byte 
calculations, requires judicious stepping of pointer registers and close 
attention to the carry flag. Fortunately, the designers of the 8080 were 
careful that these operations should seldom clash, The prototype multiple 
precision sequence is integer subtract, presented here for *bc ~ *nl: 


a = "bo - "hl -> 9be = "(be + 1) -^ "(hl + 1) -> *nc 


This chain can be extended to arbitrary length, or placed in a loop; to 
do eight bytes, for example: 


de -» sp 
esa 
a = *be + "hl -> "bc 


a = "(bo + 1) -° *(hl + 1) -> "bo 
e- 1jnzL 
de <= sp 


Clearly, addition can be performed the same way by using the "4^" 
operator. 


Comparing multiple precision operands is analogous to one byte tests: 


TO JUMP IF CODE 

be € "nl a = *bo.- "hl = "(bo + 1) -^ *(hl + 1) jm X 

*be a= "be - "hl s "(bo + 1) -° "(hl + 1) Jp X 

be a = "bo tt "hl jnz T = *(bo + 1) :: "(hl e 1) jz X; T: 
*be a = "be tr #hl jnz X = "(bo + 1) :: *(hl + 1) jnz X 
*bo > *hl sp <= bo <= hl => bo => hl; / see (*bo < 'hl) 

"bo <= "hl sp <= be <= hl => bo => hl; / see ("bo >= *hl) 


Once again, these are incorrect if the arguments differ widely enough to 
cause overflow (jp/jm), but are always correct for unsigned compares 
(320/30). 
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To test the integer at "hl against zero: 


CODE 

= "(hl +1) | a jmX 
*(hl +1) | a jp X 
hl | "(hls 1) jz X 
“hl | #(hl + 1) jnz X 
-a- #(h +4) jm X 
-a- "(nl + 1) jp X 


a 
a 
a 
a 
a 
a 


All of these operations extend easily to more bytes of precision. Note, 
however, that C represents longs and doubles in such a way that often only 
"(hl + 1), or *hl and *(hl + 1) at most, need be inspected to determine 
the value of the whole. 


As a final note, space on the stack must frequently be bought and sold as 
control blocks are entered and left. In the general case 


hl = N+ sp -> sp 


is the best way to add a constant N to sp. If N is even and less than 10, 
however, it is quicker to push or pop a register several times: 


sp <= af <= af / reserve 4 bytes 
sp => af => af / pop 4 bytes 


af is a good candidate for popping junk into, since it is highly volatile. 
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NAME 
Summary - A-Natural in brief 


FUNCTION 
Symbols may be defined as one of: 


a)  one-byte constants (kept to two bytes of precision) 

b)  two-byte constants, which may be relocatable addresses 
c) memory references 

Definition occurs by either: 

a) X :- Y defines X as Y 

b) X: defines X as . 

Code generation is directed: 


a) into the text section initially, for literals at the end, and after 
iz etext". 


b) into the data section, after ". := .data" 

Code generation occurs for: 

a) a one-byte term alone, giving a byte of that value 

b) a two-byte term alone, giving two bytes of that value 
e) a string, giving a byte for each character in the string 


d) a space reservation, giving n zero bytes for ". «[n]" 


€) a binary operator X op Y, giving the appropriate instruction bytes 
Terms are modified by: 

&)  unary operator of the form «op» X 

b)  subsoripts of the form X[n], where n is an absolute constant. 

A string is either a literal string or the result of the comma conoatena- 
tion operator. Valid operands for comma are one-byte constants, two-byte 
absolute constants, and stríngs. 

Unary operators are: 


a)  "&" to make a two-byte constant 


b) "an to make a memory reference, or to indirect on a register 
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c) "+" to do nothing to an absolute number 
d)  "-" to negate an absolute number 

e) "I" to ones complement an absolute number 
f) "=" to generate a two-byte literal 

E) public to make a symbol known across files 


Binary operators, and their valid operands, use the following abbrevia- 
tions: 


a) Cr is short for (a, d, c, d, e, h, l, *hl). 
b) Ir is short for (bc, de, hl, sp} 

c) Nis a one-byte constant. 

d) NN is a two-byte constant. 

e) Mis a memory reference. 

f) X=Y is equivalent to Y -> X. 

g) X <= Y is equivalent to Y => X. 

h) X <> Y is equivalent to Y <> X. 


Operations are evaluated left to right, except as modified by parentheses. 
The left operand is evaluated first and is retained for all subsequent 
operations. The valid forms are: 


BYTE OPERATIONS WORD OPERATIONS 
Ir 
Ir 
hl 
hl 
sp 
be 
bo 
de 
de 
a+cCr hl 
a+Nn hl 
Cr -1 bo 
a - Cr de 
N hl 
Cr af 
N be 
Cr de 
N 
r 


OoQPe»»»po 


hl 
[5 af 
N hl 
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CONDITIONALS 
jmp X 
jnz X 
jz X 
jno X 
je X 
jpo X 
dpe X 
jp x 
jn X 


OTHER PREDEFINED CONSTANTS 


cene 
daa 
di 
ei 
hlt 
in 
nop 
out 
ste 


call X 
cnz X 
ez X 
one X 
ec x 
epo X 
cpe X 
ep X 
em X 


rsto 
rsti 
rst2 
rst3 
rst 
rst5 
rst6 
rst? 


-3- 


hl © de 
hl + Ir 
Ire 
Ir-1 
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II. Programming Utilities 


the programming utilities 

using the utilities 

writing read-only code 

A-Natural translator 

A-Natural assembler for 8080 
multi-pass command driver 

maintain CP/M diskettes 

binary file editor/debugger 
translate A-Natural relocatable files 
translate object file to ASCII formats 
maintain libraries 

combine object files 

order libraries 

parse C programs 

generate code for 8080 C programs 
preprocess defines and includes 
produce execution profiie 

Pascal to C translator 

examine object files 


Introduction TX. Programming Utilities Introduction 


NAME 
Introduction - the programming utilities 


FUNCTION 
The utilities described in this section are provided with the Idris 
operating system, or with a cross-compiler on any other operating system, 
to build and debug programs written in assembler, C, or Pascal. Since 
modules may be separately translated to object code, then combined (by 
link) in one or more stages to make an executable entity, each module can 
be written in the most appropriate of the languages supported. 


Libraries may be constructed (by lib) from modules that are included only 
as needed (by link) in building a program. Thus, the library routines 
provided impose no space penalty fon programs that don't use them; and 
each user is at liberty to add to this set or alter any of its members. 


Unless explicitly labelled as machine dependent, every utility in this 
section can be used to develop programs for any of the machines supported 
by Whitesmiths, Ltd. compilers, This enhances uniformity of language im- 
plementation and simplifies programming for more than one target machine, 


BUGS 
On systems where the code generator (p2) talks to an existing, non-Idris, 
assembler, many of these utilities are not provided; hence, much of this 
section may be irrelevant. 
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WAME 
Conventions - using the utilities 


FUNCTION 

Each of the utilities described in this section is a separate "program" 
that may be run, or "invoked", by typing a "command line”, usually in 
response to a "prompt" such as the Idris "$ ". This document provides a 
systematic guide to the conventions that govern how command lines are 
Specified. It also summarizes the layout of the individual utility 
descriptions that follow, so that you know what information appears where, 
and in what format. 


Command Lines 


In general, a command line has three major parts: a program name, an op- 
tional series of flags, and a series of non-flag arguments, usually given 
in that order.  Eaoh element of a command line is usually a string 
Separated by whitespace from all the others, Most often, of course, the 
program name is just the (file) name of the utility you want to run. 
Flags, if given, change some aspect of what a utility does, and generally 
precede all other arguments, because a utility must interpret them before 
it can safely interpret the remainder of the command line. 


The meaning of the non-flag arguments strongly depends on the utility 
being run, but there are five general classes of command lines, presented 
here (where possible) with examples taken from the portable software 
tools, since they run much the same way on many different systems: 


1) program name and flags followed by a series of filenames, These 
programs (called filters) process each file named in the order 
Specified. An example is sort. 


2) program name and flags followed by a series of arguments that are not 
filenames, but strings to which the program gives some other inter- 
pretation. echo is one such utility. 


3) program name and a mandatory argument, which precedes the rest of the 
command line, followed by flags and other arguments. grep and tr 
belong to this class. 


^) program name and flags followed by a series of "source" filenames, 
and a single "destination" filename. A filename to be paired with 
each source name is created by applying "pathname completion" to the 
destination name; for instance, the destination filename might be a 
directory of files whose names match the source filenames. These 
programs (called directed utilities) then perform some operation 
using each pair of files. diff is one example. 


5) program name and flags followed by a command line that the utility 
executes after changing some condition under which ít will run. 
These tend to be more sophisticated tools, like error, which 
redirects error messages under Idris. 
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A summary of the command line classes looks like this: 


Class Example Syntax 
filter sort <progname> <flags> <files> 
string 

arguments echo <progname> «flags? «args? 
mandatory 

argument grep <progname> «arg» «flags» «files» 
directed diff <progname> «flags» «files» «dest» 
prefix error <progname> «flags» «command» 


Note that, in general, «flags? are optional in any command line. 
Flags 


Flags are used to select options or specify parameters when running a 
program. They are command line arguments recognized by their first 
character, which is always a '-' or a '«'. The name of the flag (usually 
a single letter) immediately follows the leading '-' or ‘+'. Some flags 
are simply YES/NO indicators -- either they're named, or they're not ~~ 
but others must be followed by some additional information, or "value". 
This value, if required, may be an integer, a string of characters, or 
just one character. String or integer values are specified as the remain- 
der of the argument that names the flag; they may also be preceded by 
whitespace, and hence be given as the next argument. 


The flags given to a utility may appear in any order, and two or more may 
be combined in the same argument, ao long as the second flag can't be 
mistaken for a value that goes with the first one, Some flags have only a 
value, and no name. These are given as a '-' or '«' immediately followed 
by the value. 


Thus all of the following command lines are equivalent, and would pass to 
uniq the flags -c and -f: 


$ uniq -c -f 
$ uniq -f -c 
$ unig -fe 


And each of the following command lines would pass the three flags -c3, 
=n, and -4 to pr: 


$ pr -c3 -4 -n file! 
$ pr -4 -nc 3 file! 
f pr -ni -o 3 file! 


In short, if you specify flags so that you can understand them, a utility 
should have no trouble, either. 


Usually, if you give tne same flag more than once, only the last occur- 
rence of the flag is remembered, and the repetition is accepted without 
comment. Sometimes, however, a flag ia explicitly permitted to occur mul- 
tiple times, and every occurrence is remembered. Such flags are said to 
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be "stacked," and are used to specify a set of program parameters, instead 
of just one. 


Another special flag is the string "--", which is taken as a flag ter- 
minator. Once it is encountered, no further arguments are interpreted as 
flags. Thus a string that would normally be read as a flag, because it 
begins with a '-' or a '«', may be passed to a utility as an ordinary ar- 
gument by preceding it with the argument "--". The string "-" also causes 
flag processing to terminate wherever it is encountered, but, unlike "--", 
is passed to the utility instead of being "used up", for reasons explained 
below. 


If you give an unknown flag to a utility, it will usually display a hint 
to remind you of what the proper flags are. This message summarizes the 
format of the command line the utility expects, and is explained below in 
the synopsis section of the psuedo-manual page. Should you forget what 
flags a utility accepts, you can force it to output this "usage summary" 
by giving it the flag "-help", which is never a valid flag argument. (If 
a utility expects a mandatory argument, you'll have to say "-help -help" 
to get past the argument.) 


Finally, be warned that some combinations of flags to a given utility may 
be invalid. If a utility doesn't like the set you've given, it will out- 
put a message to remind you of what the legal combinations are. 


Files 


Any utility that accepts a series of input filenames on its command line 
Will also read its standard input, STDIN, when no input filenames are 
given, or when the special filename "-" is encountered. Hence sort can be 
made to read STDIN just by typing: 


% sort 


while the following would concatenate file1, then STDIN, then file2, and 
write them to STDOUT: 


$ cat file!) - file2 


Naturally, whenever STDIN is read, it is read until end-of-file, and so 
should not be given twice to the same program. 


Manual Pages 


The remainder of this document deals with the format of the manual pages 
describing each of the utilities. Manual pages are terse, but complete 
and very tightly organized. Because of their general spareness, getting 
information out of them hinges on knowing where to find what you're after, 
and what form it's likely to take when you find it. Manual pages are 
divided into several standard sections, each of which covers one aspect of 
using the documented utility. So, for clarity, the rest of this document 
is presented as a psuedo-manual page, with the remarks on each section of 
a real page appearing under the normal heading for that section. 
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NAME 
name - the name and a short description of the utility 


SINOPSIS 
This section gives a one-line synopsís of tne command line that the 
utility expects. The synopsis is taken from the message that the 
flag -help will cause most utilities to output, and indicates the 
main components of the command line: the utility name itself, the 
flags the utility accepts, and any other arguments that may (or must) 
appear. 


Flags are listed by name inside the delimiters "-[" and "]". They 
generally appear in alphabetic order; flags consisting only of a 
value (see above) are listed after all the others. If a flag in- 
cludes a value, then the kind of value it includes is also indicated 
by one of the following codes, given immediately after the flag name: 


Code Kind of Value 

* String of characters 
Li integer (word-sized) 
Hu integer (long) 

? single character 


A '$' designates an integer representable in the word size of the 
host computer, which may limit it to a maximum as small as 32,767 on 
some machines. A "$4" always designates a long (four-byte) integer, 
which can represent numbers over two billion. An integer is inte 
preted as hexadecimal if it begins with "Ox" or "OX", otherwise as 
octal if it begins with '0', otherwise as decimal. A leading '«' or 
'-' sign is always permitted. 


If a flag may meaningfully be given more than once (and stacks its 
values), then the value code is followed by a '^'. 


Thus the synopsis of pr: 
pr -[cf ef h 1£ n n s? t* wt +## $F) <files> 


indicates that pr accepts eleven distinct flags, of which -c, -e, -l, 
and -w include word-sized integer values, -h, -m, and -n include no 
values at all, -t includes a string of characters, -s includes a 
single character, and the two flags +## and -## are nameless, con- 
sisting of a long integer alone. 


Note that flags introduced by a '-' are shown without the '-'. 
Roughly the same notation is used in the other sections of a manual 
page to refer to flags. In the pr manual page, for example, -c# 
would refer to the flag listed above as c#, while -[c# e£ wł] would 
refer to the flags "cé e$ wf". 


The position and meaning of non-flag arguments are indicated by 


"metanotions", that is, words enclosed by '<' and '>' (like «files? 
in the example above). Each metanotion represents zero or more argu- 
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ments actually to be given on the command line. When entering a com- 
mand line, you type whatever the metanotion represents, and type it 
at that point in the line. In the example, you would enter zero or 
more filenames at the point indicated by «files». 


No attempt is made in this section to explain the semantios of the 
command line -- for example, combinations of arguments that are il- 
legal. The next section serves that purpose. 


FUNCTION 


This section generally contains three parts: an overview of the 
operation of the utility, a description of each of its flags, then 
(if necessary) additional information on how various flags or other 
arguments interact, or on details of the utility's operation that af- 
fect how it is used. 


Usually, the opening overview is brief, summarizing just what the 
utility does and how it uses its non-flag arguments. The flag 
descriptions following consist of a separate sentence or more of in- 
formation on each flag, introduced by the same flag name and value 
code given under SYNOPSIS. Each description states the effect the 
flag has if given, and the use of its value, if it inoludes one. The 
parameters specified by flag values generally have default settings 
that are used when the flag is not given; such default values appear 
at the end of the description. Flags are listed in the same order as 
in the synopsis line. 


Finally, one or more paragraphs may follow the flag descriptions, in 
order to explain what combinations of flags are not permitted, or how 
certain flags influence others. Any further information on the 
utility of interest to the general user is also given here. 


RETURNS 


When it finishes execution, every utility returns one of two values, 
called success or failure. This section states under what conditions 
a utility will return one rather than the other. A successful return 
generally indicates that a utility was able to perform all necessary 
file processing, as well as all other utility-specific operations. 
In any case, the returned value is guaranteed to be predictable; 
this section gives the specifics for each utility. 


Note that the returned value is often of no interest -- it can't even 
be tested on some systems. But when it can be tested, it is in- 
strumental in controlling command scripts. 


EXAMPLE 
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Here are given one or more examples of how the utility can be used. 
The examples seek to show the use of the utility in realistic ap- 
plications, if possible in conjunction with related programs. 


Generally, each example is surrounded by explanatory text, and is set 
off from the text by an empty line and indentation. In each example, 
lines preceded by a prompt (such as "$ ") represent user input; 
other lines are the utility's response to the input shown. 
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FILES 


This section lists any external files that the utility requires for 
correct operation, Most often, these files are system-wide tables of 
information or common device names, 


ALSO 

Here are listed the names of related utilities or tutorials, which 
Should be examined if the current utility doesn't do quite what you 
want, or íf its operation remains unclear to you. Another utility 
may come closer, and seeing the same issues addressed in different 
terms may aid your understanding of what's going on. 


Other documents in the same manual section as the current page are 
simply referred to by title; documents in a different section of the 
Same manual are referred to by title and section number. 


This section documents inconsistencies or shortcomings in the 
behavior of the utility. Most often, these consist of deviations 
from the conventions described in this manual page, which will always 
be mentioned here. Known dangers inherent in the improper use of a 
utility will also be pointed out here. 


There is a fine line between being terse and being cryptic. 
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NAME 


ROM - writing read-only code 


FUNCTION 


The C compiler never generates self modifying code. If all instructions 
are steered into the text section at code generation time (as is the 
default), then the composite text section produced by the program línker 
can safely be made read only. This means that a program to be run under 
an operating system can have its text section write protected every time 
it is dynamically loaded. 


This also means that a free-standing program can have its text section 
"burned" into ROM (Read Only Memory) for any of the myriad reasons that 
people find to do so. A free-standing program usually has other issues to 
contend with as well, however. 


Each program has a data section, in addition to its text section, This 
contains all static and extern declarations, with their initial values. C 
provides no way to distinguish parameters and tables, which never vary 
during program execution, from variables with important initial values, 
from variables that need not be initialized. The safest thing to do, 
therefore, is to assume the entire data section consists of variables with 
important initial values -- and, therefore, that an inítial image of the 
data section must be copied from someplace in ROM to the expected addres- 
ses in RAM (Random Access Memory, which is writable), at program startup. 


This is not a major burden. At program startup, a free-standing C program 
must have its stack setup -- for autos, arguments, and function call 
linkages. It is just a bit more work to copy the initial data image. The 
universal link utility is easily instructed to relocate the data section 
for its eventual RAM destination, while the hex utility can place it fol- 
lowing the text section in ROM. The link utility also can be instructed 
to define symbols at the end of the text section and the end of the data 
section in its output file. Thus an initialization routine to copy data 
from ROM to RAM can simply step through memory from the "end of text" sym- 
bol to tne "end of data" symbol. 


There are ways to decrease the amount of data that must be initialized 
this way, sometimes to none at all. First there are literals -- character 
strings, switch tables, and constants -- that the compiler generates of 
its own accord. On a machine that supports separate instruction and data 
spaces, literals are steered by default into the data section. Specifying 
the flag -x6 to the code generator encourages it to put literals in the 
text section. It is rare that a ROM-based system also uses separate in- 
struction and data spaces. 


Similarly, extensive tables that are known to be read only can be col- 
lected into one C source file and compiled with the flag -x7 to the code 
generator, thus placing all data declarations for that file in the text 
section. 


If the remaining variables can be contrived to require no initialization 
at startup, or to require only a simple initialization, such as all zeros, 
then the data section can be simply discarded at ROM burning time. This 
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approach requires, naturally, that all of the source code be available for 
serutiny. 


One case where this is not possible is when library functions, available 
only in binary, are incorporated into a ROM-based, or shareable, product. 
Libraries provided by Whitesmiths, Ltd. contain no gratuitous barriers to 
being shared. A function such as exp, for instance, contains only tables 
in its data section -- it may safely be passed through the Linker to have 
its data merged into its text section. 


Some functions, however, of necessity contain static variables with impor- 
tant initial values. Usually these functions interact with operating 
System services and hence are not found in ROM-based programs. Examples 
are onexit/exit, which remembers the head of a list of functions to be 
called on program exit, and sbreak, which may hold the current end of the 
dynamic data area. Still other functions with static variables may find 
use in free standing programs -- examples are alloc/free and when/ raise. 


The best practice, therefore, is to adopt the most general startup 
initialization described above. It is often too hard to determine which 
library functions are safe, and even harder to remember special rules for 
keeping new code safe. 
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NAME 

anat - A-Natural translator 
SINOPSIS 


anat -[i o* s*] «files? 


FUNCTION 


anat translates A-Natural narrative assembly language for the Intel 8080 
to standard assembly language as accepted by either the ISIS-II asm80 or 
the Microsoft Macro-80 assembler, Since the output of the 8080 code 
generator p2.80 is A-Natural, anat is required to interface the C compiler 
to existing 8080 software development facilities. 


The flags are: 


-i emit code in ISIS-II format, in which identifiers have each '.' 
changed to '@' and each ' ' changed to '?'. Default is Microsoft 
format, in which each '.' is changed to '$' and each ' ' is changed 
to *.*. 


-o* write the output to the file * and write error messages to STDOUT. 
Default is STDOUT for output and STDERR for error messages. 


-s* emit an end statement with the operand *, to specify a starting 
address. Default is to emit an end statement with no start address. 


If «files? are present, they are conoatenated in order and used as the in- 
put file instead of the default STDIN. 


If -o is absent, and one or more files are present, and tne first filename 
ends with '8', then anat behaves as if -o was specified using the first 
filename, only with the trailing '8' changed to 'm'. Thus, 


anat file.8 
ís the same as 
anat -o file.m fiie.8 


If -o is present, a name directive (title for Microsoft) is emitted using 
the output file name as the module name; a .suffix in the name is 
stripped off. If there is no -o, but <files> are present, then the first 
input file name is used in the name directive. If neither is present, no 
name directive is emitted. 


Code generation begins in cseg, and reverts to cseg at the end before any 
literals are emitted. Any symbols not defined by the end of the input 
file are published vía extrn statements at the end. 


II - 


The start string used with -s does not have '.' and ' ' mapped as for 
identifiers. 
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NAME 
as.80 - A-Natural assembler for 8080 


SYNOPSIS 
as.80 -[o* x] «files? 


FUNCIION 
as.80 assembles A-Natural narrative assembly language for the Intel 8080 
to standard format relocatable object images. Since the output of the 
8080 code generator p2.80 is A-Natural, as.80 is required to produce 
relocatable images suitable for binding with link. 


The flags are: 


=o% write the output to the file *. Default is xeq. Under some circum- 
stances, an input filename can take the place of this option, as ex- 
plained below. 


-x place in the object image only those symbols that are undefined or 
that are to be made globally known. Currently, this happens anyway; 
the flag is present for compatibility with other assemblers. 


If «files? are present, they are concatenated in order and used as the in- 
put file instead of the default STDIN. 


If -o is absent, and one or more files are present, and the first filename 
begins with 's', then as.80 behaves as if -o were specified using the 
first filename, only with the trailing 's' changed to 'o'. Thus, 


as.80 file.s 
is the same as 
as.80 -o file.o file.s 


A relocatable object image consists of an eight-word header followed by a 
text segment, a data segment, the symbol table, and relocation informa- 
tion. The header consists of the value 0x1499, the number of symbol table 
bytes, the number of bytes of object code defined by the text segment, the 
number of bytes defined by the data segment, three zero words, and the 
data segment offset, which always equals the text segment size. All words 
in the object image are written less significant byte first. The text 
segment is relocated relative to location zero, the data segment is 
relocated relative to the end of the text segment. 


Relocation information consists of two byte streams, one for the text seg- 
ment and one for the data segment, each terminated by a zero control byte. 
Control bytes in the range [1, 31] cause that many bytes in the correspon- 
ding segment to be skipped; bytes in the range [32, 63] skip 32 bytes, 
plus 256 times the control byte minus 32, plus the number of bytes 
specified by the relocation byte following. 


All other control bytes control relocation of the next word in the cor- 
responding segment. The 1-weighted bit and 2-weighted bit are both always 
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zero for the 8080; the symbol code is the control byte right shifted two 
places, minus 16. 


A symbol code of 47 is replaced by a code obtained from the byte or bytes 
following in the relocation stream. If the next byte is less than 128, 
then the symbol code is its value plus 47; otherwise the code is that 
byte minus 128, times 256, plus 175 plus the value of the next relocation 
byte after that one. 


A symbol code of zero calls for no further relocation; 1 means that a 
Change in text bias must be added to the word; 2 means that a change in 
data bias must be added; 3 is not used. Other symbol codes call for the 
value of the symbol table entry indexed by the symbol code minus 4 to be 
added to the word, 


Each symbol table entry consists of a value word, a flag byte, and a nine- 
byte name padded with trailing NULs. Meaningful flag values are 0 for un- 
defíned, à for defined absolute, 5 for defined text relative, and 6 for 
defined data relative. To this is added 010 if the symbol is to be 
globally known. 


SEE ALSO 
link, p2.80, rel 
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NAME 
c - multi-pass command driver 


SYNOPSIS 
c -[f* of pë v +#) «files» 


FUNCTION 
c is designed to facilitate multi-pass operations such as compiling, as- 
sembling, and linking source files, by expanding commands from a prototype 
script for each of its file arguments, It is best described by example. 
A script for Pascal compilation on the PDP-11 might look like: 


pi/etc/bin/pte ptc 
e:/etc/bin/pp pp -x -i/1ib/ 
1/odd/pi p! -cem 
:/odd/p2. 11 p2 
s:/etc/bin/as as 


o::/eto/bin/link link -lp.11 -1c.11 /lib/Crts.o 


c is intended for installation under multiple aliases, Each alias nor- 
mally implies the name of a ",proto" file containing a corresponding 
script, to be searched for in the same way that the shell looks for the 
file named by a command. That is, if the alias contains a '/', then only 
the directory named is searched} otherwise, the search is of each direc- 
tory in the current execution path. If the scrípt above were named 
pc.proto, it could be implicitly invoked by running c under the alias po. 
The -f flag may be used to override this lookup procedure. 


By convention, the alias c is a synonym for the host machine native C com- 
piler driver, and pc for the host Pascal driver. 


Given the script above, c would produce a ".o" file for any argument files 
ending in ".p" by executing the following command list: 


COMMAND ARGUMENTS 
/etc/din/pte pte -o T] file.p 
/etc/bin/pp pp -o T2 -x -i/lib/ T1 
/odd/p1 pl -o T1 -cem T2 
/odd/p2.11 p2 -o T2 T1 
/etc/bin/as as -o file.o T2 


where file.p is the argument file, and T1 and T2 are temporary inter- 
mediates, 


Files whose names end in ".o" would be processed beginning at tne script 
line labelled "c:"; similarly, ".s" files would be processed starting at 
the line labelled "s:". In general, all ".o" files produced, plus any 
files whose suffix matches no line prefix, are collected and passed to the 
link program for final binding. A file is passed to the link program only 
if its name is not already in the argument vector of the link line. Any 
error reported by any of the processing programs terminates processing of 
the current file; if any files are terminated the link program is not run. 
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The flags are: 


-f* take prototype input from file * instead of from the ".proto" file 
implied by the command line alias. If * is "-", STDIN is read. 


-oë place the output of the link line program in file * (by prepending 
-0* to its argument list). The prepending occurs only if this flag 
is given; naturally, it should be given only if the program will ac- 
cept a -o specification. 


-p* prefix the names of all permanent output files with the pathname *, 
If the -o flag is given, then the link line output filename will also 
be prefixed with *, if it doesn't already contain a '/'. All other 
Output fíles will be stripped of any pre-existent pathname before 
being prefixed. 


-v before executing each command, output its arguments to STDOUT. The 
default is to output only the name of each processed file and the 
name of the linker when (and if) it is run, each name followed by a 
colon and a newline. 


** stop production at prototype line whose prefix is '*. The string 
given is matched against the prefix fields of each prototype line, 
and execution of prototype commands halts after the line preceding 
tne matching one. In the example above, +c would cause ".p" files to 
be converted to ".c" files, with no subsequent processing, «s would 
process ".p" or ".c" files to ".s", and +0 would inhibit linking. 
Any file that results in no processing causes an error nessage. 


Each line in the prototype file has up to four parts: a prefix string 
(perhaps null) terminated with a colon, a pathname specifying a program to 
be run, and one or two groups of up to 16 strings, the groups separated by 
a colon. An argument vector is constructed for each program from the 
first string in the first group, a -o specification, the remaining strings 
in the first group, and one of the argument files. The second group of 
strings, if present, is appended to the vector after the argument file. 
Each entry on the command line is delimited by arbitrary whitespace. The 
final line in the file may have a prefix field (and colon) alone, in which 
case it specifies only the output file suffix for the preceding line. The 
final line may also have a prefix field terminated with a double colon, 
defining it as a "link line" with the special characteristics noted above. 


Note that a prototype line with a null prefix field cannot be specified by 
the user as an entry or exit point. 


If the last line of a prototype ís not a prefix only and not a link line, 
then its output is written to a temporary file, which is discarded. 


RETURNS 
c returns success if it succeeded in passing all of its command line files 
to at least one of the prototype programs (the link line program in- 
cluded), and if all of the executions it supervised returned success. 
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EXAMPLE . 
A prototype file to do C syntax checking only, with no code generation, 
might be: 


e:/etc/bin/pp pp -x -i/lib/ 
1/odd/p1 pt 


This prototype would produce no output files, since the output of p1 would 
go to a temporary file. 


BUGS 
Needs some way to specify flags to the prototype programs. 


This utility is currently provided for use only on Idris/UNIX host 
systens. 
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cpa II. Programming Utilities opa 
NAME 
cpu - maintain CP/M diskettes 
SINOPSIS 
cpm -[«epm dee bc d p r t v x f*] «files» 
FUNCTION 


cpm reads and writes CP/M compatible filesystems written on standard 
eight-inch, soft-sectored, IBM compatible diskettes. Such filesystems ad- 
minister a diskette by dividing it into 243 clusters of 1024 bytes; up to 
16 clusters may be allocated to an extent; up to 64 extents may be en- 
tered into the directory. A file consists of one or more extents, num- 
bered consecutively from zero. All extents belonging to the same file 
have the same eight-character name and three-character type; names and 
types are best limited to letters of one case and digits, for maximum por- 
tability. 


The flags are: 
«eps Convolve the sectors on each track by the recipe: 
sec = (sec * 6 + (13 <= sec)) $ 26; 
where sec is in the interval [0,26), i.e. one less than the hardware 
sector number, This option is necessary on those machines that write 
diskette sectors without convolving, i.e. starting with track 0 sec- 
tor 1 for seek address OL and taking subsequent sectors sequentially. 


-dec Deconvolve the sectors to correct for DEC convolution. The DEC 
recipe is: 


sec = ((seo << 1) + (13 <= sec) + trk * 6) $ 26; 
trk ze 15 


where sec is as above, and trk is in the interval [0,77). This op- 
tion is necessary on DEC systems such as RT-11 and RSX-11M; the CP/M 
reconvolving also takes place as above. 


-b Treat all files to be copied as binary images. Default is text mode, 
with possible processing of carriage returns, nulis, control-Z codes, 
etc. 


-a Create new diskette with empty directory, then copy named files to 
diskette. 


-d Delete named files from diskette. 


-f* Diskette is accessed as filename *, Default is "dx0:" if -dec flag 
is present, else "/dev/rxO", 


-p Print files, i.e. copy them from diskette to STDOUT. If no files are 
specified, all files are printed. 
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RETURNS 


-r 


-t 


wv 
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Replace named files on diskette. 


Tabulate the diskette directory, showing all allocated extents in al- 
Phabetical order. 


Be verbose about operations, naming files deleted "d:", added "a:", 
or extracted "x:", List number of free extents and clusters if -t is 
specified. Default is reasonably silent operation, save for errors. 


Extract files, i.e. copy them from diskette to files with the same 
name, If no files are specified, all files are extracted. 


At most one of the flags -c, -d, -p, -r, -t, +x may appear; default is 


-t. 


opm returns success if the directory structure of the diskette is intact 
and no file transfers failed, else failure. 


To ereate a diskette and check it, under a DEC operating system: 


>cpm -dee -c escrip.omd lsorip.omd 
>cpm -dec -rb prog.com 

>epm -dec 

>epm -dec -p cscrip.cnd 
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II. Programming Utilities db 


db - binary file editor/debugger 


SYWOPSIS 


db -[a c n p u] «file» 


FUNCTION 


db is an interactive editor designed to work with binary files. It 
operates in one of three modes: 1) as a binary file editor, for inspect- 
ing and patching arbitrary direct access files, such as disk images or en- 
coded data files; 2) as a "prepartum" debugger, for inspecting and patch- 
ing executable or relocatable files; and 3) as a "postmortem" debugger, 
for inspecting core images produced by the system, possibly using informa- 
tion from the original executable file. In the latter two cases, db 
recognizes the structure of object, executable, and core files, and does 
Special interpretation of addresses to simulate the runtime placement of 
code and data. 


db contains a disassembler enabled by specifying the mode 'm' in the o, p, 
or 1 commands (also used by the d and s commands, and in context search- 
ing). The disassembler interprets the file as machine instructions and 
translates them into conventional symbolic notation, using a symbol table 
and relocation information, when available, to output addresses. This 
"machine mode" is the initial default used for files not flagged as ab- 
solute. 


A different disassembler is incorporated into db for each target machine 
to be supported. Thus, there may be variations with names like db11, 
db80, etc. By convention, the debugger for the host machine is called db. 


The flags are: 
-a treat <file> as an absolute binary file. 


-c use the file core along with <file> and operate in debug mode. core 
Will be the initial current file. 


-n suppress the output of the current byte number normally preceding 
each item displayed. 


-p write a prompt character '>' to STDOUT before reading command input. 
By default, no prompt ís output. 


-u open <file> in update mode, By default, <file> is opened for reading 
only. 


At most one of -a and -o may be specified. Any core image file must al- 
ways be named core. If «file» is not specified, xeq is assumed. 


db has a great deal in common with the text editor e. It operates on the 
current binary file, a corresponding core image, or both, by reading from 
STDIN a series of single-character commands, and writing any output to 
STDOUT. Just as commands in e may be preceded by line addresses, db com- 
mands may be preceded by byte addresses, the syntax of which is a superset 
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of e address syntax. Analogous commands in the two editors have the same 
name; default behavior is also similar. 


db imposes no structure on the data contained in its input files, except 
that implied by the current input/output mode, which defines the length of 
the "items" on which many commands operate. Outside machine mode, an item 
is one, two, or four bytes of the file. In machine mode, an item is the 
instruction disassembied starting at the current location, and is of 
varying length. Byte ordering of multiple-byte items is determined by the 
target machine, as are other machine-dependent characteristics such as 
symbol table structure and the size of an int. Thus, examining a file 
created for some machine other than the target is inadvisable. If <file> 
cannot be interpreted as an object file in standard format for the target 
machine, it is treated as absolute. If a core file does not begin with 
control bytes appropriate for the target, db aborts. 


Address Interpretation and Syntax 


In an absolute file, a byte address is simply the location of a byte rela- 
tive to the start of tne file (the first byte having address zero). In 
object or core files, an address consists of two components: the memory 
location a byte would oceupy if the current file were actually loaded, and 
a flag indicating whether the location is within the text segment or 
within the data/bss segment of the program. (The program's bss segment 
immediately follows its data segment.) The ranges of addresses in the two 
segments may overlap; an address that could refer to either space is 
disambiguated as explained below. 


A byte address is a series of one or more of the following terms: 


The character  '.' addresses the "current byte" (or "dot"). 
Typically, dot is the first byte of the last item affected by the 
most recent command (but see the command descriptions below for 
specifics). Dot also refers to the same segment as that item. 


The character '$' addresses the last byte of the segment to which dot 
currently refers. For an absolute file, '$' has no meaning. A re- 
quest to examine or change a given address will result in a seek to 
that byte of the file; the request succeeds if the subsequent I/O 
call does. 


In an object file, the characters 'T', 'D', and 'B' are oonstants 
that have the value of the first address in the text, data, and bss 
segments, respectively, and also have the appropriate segment compo- 
nent. In a core file, 'T' and 'D' have the same meaning, while 'B' 
is set to the address of the top of stack at the time of the dump, as 
recorded in the core file panel. All three have the value zero if 
tne current file is absolute. 


An integer n addresses the nth byte of an absolute file, where bytes 
are numbered from zero. In an object or core file, an integer n ad- 
dresses the nth byte of "memory", and the segment specified by the 
most recent term with an explicit segment component (or that of dot, 
if no such term exists). The easiest way to address the nth byte of 
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one of the two segments is to add an integer n to one of the con- 
Stants 'T', 'D' or 'B'. An integer is interpreted as octal if it 
begins with '0', as hexadecimal if it starts with "Ox" or "OX", and 
as decimal otherwise. 


"'x", a single-quote followed by any lower-case letter, addresses the 
byte that has been previously assigned that letter, as described in 
the k command below. 


A regular expression, enclosed in '/', causes a context search of the 
current segment (or of the whole file, if it is absolute), starting 
with the item after the current byte and proceeding toward the end of 
the current segment (or file). Syntax for regular expressions is the 
same as that for e, i.e., as implemented by the portable C library 
routines amatch, match, and pat. Each item in the region searched is 
converted to the current output format, and compared with the search 
String given. The search stops at the first matching item, the value 
of the term being the address of that item. An error is signaled if 
the search fails. 


A regular expression enclosed in '$' or '?' causes a backward search. 
The context search starts with the item before the the current byte, 
and proceeds toward the start of the current segment (or of the file, 
if it is absolute), as described above. A backward search is im- 
possible if the current output mode is machine mode. 


A string beginning with a ' ' or a '"' is taken to be a symbol name, 
terminated by whitespace or by one of the operators given below. A 
leading ' ' is taken as part of the name; a leading '"' introduces 
names not starting with a ' ', and is discarded. The value of the 
term is the address of the symbol; the segment referenced by the 
term is the one in which the symbol is defined. 


A term may be followed by an arbitrary number of '*', each of which causes 
the value calculated to its left to be treated as a pointer into tne data 
segnent. The contents of the int-sized location pointed at then become 
the value of the term. Postfixing a term with '>' causes it to be 
analogously treated as a pointer into the text segment. 


An address is resolved by scanning terms from left to right. Two terms 
separated by a plus '+' (or a minus '-'), resolve to a term that is the 
sum (or difference) of the values of the two original terms. Two succes- 
sive terms not separated by an operator are summed. If a term explicitly 
refers to one of the two segments, then that segment becomes the segment 
to which the entire address refers. 


If an address begins with a '+' or '-', then dot is assumed to be a term 
at the left of the '+' The symbol '^' is equivalent to '-' in 
this context. Thus, "^3" standing alone is taken to be the same as ",.-3". 


A ‘+t ('-t or 5^!) not followed by a term is taken to mean «1 (-1). Thus 
'-' alone stands for ".-1", "++" stands for ".42", "6---" stands for "3" 
and so on. 


II - 19 


db 


-4- db 


An address may be arbitrarily complex, so long as it yields a value within 
the bounds of the segment it refers to. (Again, for an absolute file, any 
address will be accepted.) There can be any number of addresses preceding 
a command so long as the last one or two are legal for that command. For 
a command requiring two addresses, it is an error for the second address 
to be less than the first, or for the addresses to refer to different seg- 
ments. In debug mode, when pointing at the core file, stack addresses are 
accepted. 


In machine instruction mode, addresses should be specified with care. db 
will disassemble starting at the address specified, but if the address is 
not the beginning of a valid instruction, the output is meaningless. To 
insure valid disassembly, start at tne beginning of the text section or at 
the address of a text-relative symbol. 


Command Syntax 


Each db command consists of a single character, which may optionally be 
preceded by one or more addresses typically specifying the inclusive range 
of bytes in the file that the command is to affect. Addresses are 
separated by a comma ',' or by a colon ':'. If a colon is used, then dot 
is set to the location and segment specified by the address to the left of 
the colon before the rest of the command is interpreted. The command 
Character may be followed by addítional parameters, Multiple commands may 
be entered on a line by separating them with semicolons. Every command 
needing addresses has default values, so addresses can often be omitted; 
db complains if an address is referred to that doesn't exist. 


In the command descriptions below, addresses in parentheses are the 
default byte addresses that will be used for the command if none are en- 
tered. The parentheses are not to be entered with the command, but are 
present as a syntactical notation. If a command ís described without 
parentheses, no addresses are required. For a two-address command, sup- 
plying only one address will default the second to be identical with the 
one supplied. It is an error to precede with addresses commands that do 
not require any. The commands aret 


(fp)a - display auto stack frame. Valid only if core is the current file. 
db keeps a pointer fp to the current stack frame, initialized to the 
one specified by the panel dumped to the core file. "a" may be 
preceded by an address whioh will be interpreted (and memorized) as 
the address of an auto stack frame. 


b(1) - backup one or more stack frames. Valid only if core is the current 
file. "b" may be followed by a zero, which reinitializes the current 
stack frame pointer fp to the one in the panel, or by a count of the 
number of frames to be backed over. "b" and this count may also be 
followed by "a", which will backup one stack frame and display the 
auto stack frame values. 


e - display the panel, which consists of the saved registers and cause of 


death. The registers are displayed in hexadecimal and symbolically, 
if meaningful. Valid only if core is the current file. 
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(.,.)d - print items that differ between executable and core files. 


e file - enter a new modifiable data file, in same mode as before, then 
memorize filename. This works with -a flag only. 


f - display name of modifiable data file. 


(.)kx - mark address by memorizing it in x, where x is any lower case let- 
ter, suitable for later recall as a pointer with 'x. 


(.,.)1«mode? ~ look at address specified, i.e., display item in output 
text representation, but don't change '.' to the address given. If 
«mode» is present, it changes the mode that was specified in the last 
'o' command. 


(.)n - display address as symbol plus offset. 


oXmode» - change output text representation to «mode», where «mode» is 
'm', indicating disassembly of machine instructions, or any of the 
combinations [al|hlo]u] [c|s|i]l], for ASCII, hexadecimal, octal, or 
unsigned display of char, short, int, or long integers. If «mode» is 
not specified, the mode is set to the default used at db invocation: 
'm' if the -a flag was not given, and unsigned short otherwise. 


(.,-)p<mode> - print item in output text representation, then change '." 
to point at last address specified. If «mode» is present, ít changes 
the mode that was specified in the last 'o' command. 


q~ quit. 


(.)r file - read binary contents of specified file and replace target file 
from current byte, extending the file as necessary. This is valid 
only with -a flag. file must not be the «file» being db'ed. 


(-,.)s/pattern/new/[g] - for all items in range, expand to output text 
representation, edit text by changing instances of pattern to new, 
then update item using edited text pattern. If g suffix is 
specified, all matches in an item are altered, otherwise only the 
leftmost is altered. 


(.)u - enter update mode, i.e., treat each subsequent line of input as the 
output text representation of an item and replace the addressed item. 
Successive items are replaced, extending the file as necessary, until 
an input line containing only a '.' is encountered. This does not 
work in 'm' mode. The input must be entered in the current mode, one 
item per line; otherwise db will complain. 


(0,$)w file - write the specified range of the file being db'ed to file. 
file must not be the same as «file» being db'ed. This command is 
valid only with -a flag. 


z file - point db at file. If file is omitted, z reports which file, core 
or executable, is currentiy pointed at. 
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(.)<mewline> - equivalent to entering ". + size", where size is the number 


of bytes being displayed in the current mode. This form can be used 
to view one instruction or item at a time. If a byte address 
precedes the <newline>, the addressed item will be displayed. Dot 
Will be set to the displayed byte. 


!Xcommand» - send all characters on the line to the right of the '!' to 


the system, to be interpreted as a system command. "Icd" is handled 
by db directly. Occurrences of the sequence "Mf" will each be 
replaced by the currently remembered file before the transfer to 
system level is made. Dot is not changed by this command, Available 
only in Idris/UNIX systems, 


display the byte number of dot. 


On Idris/UNIX systems, if an ASCII DEL is typed, db interrupts its current 
task, if any, and displays '?'. It then will be ready to accept db com- 
mands again. Dot is generally ill-defined at this point. 


SRE ALSO 


link, rel 


BGS 


This utility is currently provided for use only on Idris/UNIX host 
systems. 
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NAME 
dis80 - translate A-Natural relocatable files 


SYNOPSIS 
dis80 -[c 1] «files» 


FUNCTION 
dis80 permits translation to symbolic form of the relocatable binary files 
produced by the A-Natural assembler as.80. This form is compatible with 
existing assembler code on an 8080. 


The flags are: 


=c Translate each file to an assembler program suitable for input to the 
Microsoft assembler under CP/M. Each underscore ' ' in an identifier 
is changed to '.', and each ',' is changed to '$'. 


-i Translate each file to an assembler program suitable for input to the 
asm80 assembler under ISIS-II. Each underscore ' C in an identifier 
is changed to '?', and each '.' is changed to '@'. 


If no flags are given, the default is -c. 


<files> specifies one or more files, which must be in A-Natural 
relocatable format. If more than one file is specified, then the output 
for each is preceded by a line of the form 


file: 


Assembler output is headed by a títle directive (name for ISIS-II), where 
the name is derived from the filename by stripping off any charaoters to 
the right of and including the leftmost '.', then appending a '8' in the 
ease of ISIS-II, and a '$' in the case of Microsoft. 


RETURNS 
dis80 returns success if no diagnostics are produced, i.e. if all reads 
are successful and all file formats are valid. Otherwise it returns 
failure, 


EXAMPLE 
To convert chdr.o for use with Microsoft assembler code: 


% dis80 chdr.o >chdr.mac 


SEE ALSO 
as.80, link 


BUGS 


The symbols " c " and " d " must not be used in A-Natural programs to be 
translated with dis80. 
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hex - translate object file to ASCII formats 


STNOPSIS 


hex -[db## dr n m* rè s tof? +# $1 <ifile> 


FUNCTION 


hex translates executable images produced by link to Intel standard hex 
format or to Motorola S-record object file format. The executable image 
is read from <ifile>. If no <ifile> is given, or if the filename given is 
"-", the file xeq is read. 


The flags are: 


~db## when processing a standard object file as input, override the object 
module data bias with ##. 


-dr output text records as record type 0x81, data records as record type 
0x82, for use with the Digital Research genomd utility under CP/M-86. 


-h don't produce start record for Intel hex files. 


-a* insert the string *, instead of <ifile>, into the Motorola S0 record 
generated when -s is given. 


-r## interpret the input file as "raw" binary and not as an object file, 
Output is produced as described below, in either format, except that 
the starting address of the module is specified by the long integer 
". 


-s produce S-records rather than the default hex format. 


-tbé$ when processing a standard object file as input, override the object 
module text bias with ##. 


+# start output with the #th byte. # should be between 0 and one less 
than the value specified by the -# flag. -4 +3 produces bytes 3, 7, 
11, 15, ...; -2 +0 produces all even bytes; -2 +1 outputs all odd 
bytes; 0 is the default, which outputs all bytes. 


-# output every #th byte. -2 outputs every other byte, -4 every fourth; 
1 is the default, which outputs all bytes. 


Output is written to STDOUT. When the input file is a standard object 
file, the load offset of the first record output for its text or data seg- 
ment is determined as follows. If an offset is explicitly given for that 
segment (with "-db##" or "-tb##"), it is used. Otherwise, if all bytes of 
the input file are being output, the appropriate bias is used from the ob- 
ject file header. Otherwise, a load offset of zero is used. Then, the 
value given with "+#" is added to the chosen offset to obtain the first 
offset actually output. 
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A file in Intel hex format consists of the following records, in the order 
listed: 


1) a '$' alone on a line to indicate the end of the (non-existent) syu- 
bol table. If -h is specified, this line is omitted. 


2) data records for the text segment, if any. These represent 32 image 
bytes per line, possibly terminated by a shorter line. 


3) data records for the data segment, if any, in the same format as the 
text segment records, 


NW) an end record specifying the start address. 

Data records each begin with a ':' and consist of pairs of hexadecimal 

digits, each pair representing the numerical value of a byte. The last 

pair is a checksum such that the numerical sum of all the bytes 
represented on the line, modulo 256, is zero. The bytes on a data record 
line are: 

&) the number of image bytes on the line. 

b) two bytes for the load offset of the first image byte. The offset is 
written more significant byte first so that it reads correctly as a 
four-digit hexadecimal number. 

c) a zero byte "00", 

d) the image bytes in increasing order of address. 

e) the checksum byte. 


An end record also begins with a ':' and is written as digit pairs with a 
trailing checksum. Its format is: 


a) a zero byte "O0", 

b) two bytes for the start address, in the same format as the load off- 
set in a data record. The start address used is the first load off- 
set output for the file. 

o) a one byte "01", 

d) the checksum byte. 


S-Record Files 


A file in Motorola S-record format is a series of records each containing 
the following fields: 


«S field><count><addr><data bytes><checksum> 
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All information is represented as pairs of hexadecimal digits, each pair 
representing the numerical value of a byte. 


<S field» determines the interpretation of the remainder of the line; 
valid S fields are "SO", "Sj", "S2", "S8", "S9". count? indicates the 
number of bytes represented in the rest of the line, so the total number 
of characters in the line is «count? * 2 + 4. 


<addr> indicates the byte address of the first data byte in the data 
field. SO records have two zero bytes as their address field; S1 and S2 
records have <addr> fields of two and three bytes in length, respectively; 
S9 and S8 records have <addr> fields of two and three bytes in length, 
respectively, and contain no data bytes. <addr> is represented most sig- 
nificant byte first. 


The SO record contains the name of the input file, formatted as data 
bytes. If input was from xeq, XEQ is used as the name. $1 and 32 records 
represent text or data segment bytes to be loaded. They normally contain 
32 image bytes, output in increasing order of address; the last record of 
each segment may be shortér. The text segment is output first, followed 
by the data segment. S9 records contain only a'two-byte start address in 
their <addr> field; S8 records contain a three-byte address, The start 
address used is the first load offset output for the file. 


<checksum> is a single byte value such that the numerical sum of all the 
bytes represented on the line (except the S field), taken modulo 256, is 
255 (OxFF). 

REIURNS 
hex returns success if no error messages are printed, that is, if all 
records make sense and all reads and writes succeed; otherwise it reports 
failure. 


EXAMPLE 
The file hello.c, consisting of: 


char *p ("hello world"); 
when compiled produces the following Intel hex file: 
f$ hex hello.o 


30E000000020068656C6C6F20776F726C640094 
20000000 1FF 


and the following Motorola $-recorda: 
5 hex -s hello.o 
S004000068656C6C6F2E6F44 
$1110000020068656C6C6F20776F726C640090 
$9030000FC 
SEE ALSO 
link, rel 
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lib - maintain libraries 


SYNOPSIS 


lib «lfile» -[c d i p r t v3 v6 v7 v x] «files» 


FUNCTION 


lib provides all the functions necessary to build and maintain objeot 
module libraries in either standard library format or those used by 
UNIX/System III, UNIX/V6, or UNIX/V7. lib can also be used to collect ar- 
bitrary files into one bucket. <lfile> is the name of an existing library 
file or, in the case of replace or create operations, the name of the 
library to be constructed, 


The flags are: 


-c create a library containing «files», in the order specified. Any ex- 
isting <lfile> is removed before the new one is created. 


-d delete from the library the zero or more files in <files>. 


=i take <files> from STDIN instead of the command line. Any <files> on 
the command line are ignored. 


=p print named files (do a -x to STDOUT), If no files are named, all 
files are extracted. 


-r in an existing library, replace the zero or more files in «files»; 
if no library <lfile> exists, create a library containing «files», in 
the order specified. The files in «files? not present in the library 
are appended to it, in the order specified. 


-t list the files in the library in the order they occur. If «files» 
are given, then only the files named and present are listed. 


-v3 create the output library in UNIX/System III format, VAX-11 byte- 
order. This flag is meaningful with -c or -r; it is mandatory for 
-t and -x (UNIX/V7 format is assumed if this flag is not specified). 


-v6 create the output library in UNIX/V6 format. Meaningful only with -o 
or =r, 


-v7 create the output library in UNIX/V7 format, PDP-11 byte-order. 
Meaningful only with -c or -r. 


-v be verbose. The name of each object fiie operated on is output, 
preceded by a code indicating its status: "o" for files retained un- 
modified, "d" for those deleted, "r" for those replaced, and "a" for 
those appended to <lfile>. If -v is used in conjunction with -t, 
each object file is listed followed by its length in bytes. 
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-x extract the files in «files? that are present in the library into 
discrete files with the same names. If no «files? are given, all 
files in the library are extracted. 


At most one of the flags -[c d p r t x] may be given; if none is given, 
-t is assumed. Similarly, at most one of the flags -[v3 v6 v7] should be 
present; if none is present, standard library file format is assumed when 
a new library is created by -r or -c. An existing library is processed in 
its proper mode, except for UNIX/III libraries, for which the flag -v3 
must be specified. 


The standard library format consists of a two-byte header having the value 
0177565, written less significant byte first, followed by zero or more en- 
tries. Each entry consists of a fourteen-byte name, NUL padded, followed 
by a two-byte unsigned file length, also stored less significant byte 
first, followed by the file contents proper. If a name begins with a NUL 
byte, it is taken as the end of the library file. 


Note that this differs in several small ways from UNIX/V6 format, which 
has a header of 0177555, an eight-byte name, six bytes of miscellaneous 
UNIX-specific file attributes, and a two-byte file length. Moreover, a 
file whose length is odd is followed by a NUL padding byte in the UNIX 
format, while no padding is used in standard library format. 


UNIX/III and UNIX/V7 formats are characterized by a header of 0177545, a 
fourteen-byte name, eight bytes of UNIX-specific file attributes, and a 
four-byte length. The length is in VAX-11 native byte order for UNIX/III 
or in PDP-11 native byte order for UNIX/V7. Odd length files are also 
padded to even. 


RETURNS 


lib returns success if no problems are encountered, else failure. After 
most failures, an error message is printed to STDERR and the library file 
is not modified. Output from tne -t flag, and verbose remarks, are writ- 
ten to STDOUT. 


EXAMPLE 


To build a library and check its contents: 


$ lib clib -r one.o two.o three.o 
$ lib clib -tv 


SEE ALSO 


link, lord, rel 


BOGS 


If all modules are deleted from a library, a vestigial file remains. 


Modifying UNIX/III, UNIX/V6, or UNIX/V7 format files causes all attributes 
of all file entries to be zeroed. 
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lib doesn't check for files too large to be properly represented in a 
library (> 65,534 bytes). 
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NAME 
link - combine object files 


SYNOPSIS 
link -[a bb## bif c db## dr# d eb* ed* etë hi 19^ of p sb* sd* stë 
tbé$ tf$ t ut^ x£] «files? 


FUNCTION 
link combines relocatable object files in standard format for any target 
machine, selectively loading from libraries of such files made with lib, 
to create an executable image for operation under Idris, or for stand 
alone execution, or for input to other binary reformatters. 


The flags are: 


-a make all relocation items and all symbols absolute. Used to 
prerelocate code that will be linked ín elsewhere, and is not to be 
re-relocated. 


-bbiH relocate the bss (block started by symbol) segment to start at $$. 
By default, the bss segment is relocated relative to the end of the 
data segment. Once ~bb## has been specified, the resulting output 
file is unsuitable for input to another invocation of link. 


-bi set the stack plus heap size in the output module header to $4. 
Idris takes this value, if non-zero, as the minimum number of bytes 
to reserve at execution time for stack and data area growth. If the 
value ís odd, Idris will execute the program with a smaller heap plus 
Stack size, so long as some irreducible minimum space can still be 
provided by using all of available memory. 


-c suppress code output (.text and .data), and make all symbols ab- 
solute. Used to make a module that only defines symbol values, for 
specifying addresses in shared libraries, etc. 


~db## set data bias to the long integer ##. Default is end of text sec- 
tion, rounded up to required storage boundary for the target machine. 


-dr$ round data bias up to ensure that there are at least # low-order 
binary zeros in its value. Ignored if -db## is specified. 


-d do not define bss symbols, and do not complain about undefined sym- 
bols, Used for partial links, i.e., if the output module is to be 
input to link. 


-eb* if the symbol * is referenced, make it equal to the first unused 
location past the bss area. 


-ed* if the symbol * is referenced, make it equal to the first unused 
location past the initialized data area. 


-et* if the symbol * is referenced, make it equal to the first unused 
location past the text area. 
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-h suppress header in output file. This should be specified only for 
stand alone modules such as bootstraps. 


-i take «files? from STDIN instead of the command line. Any <files> on 
the command line are ignored. 


-1* append library name to the end of the list of files to be linked, 
where the library name is formed by appending * to "/lib/lib", Thus 
"-1c.1l1" produces "/lib/libc.i1". Up to ten such names may be 
Specified as flags; they are appended in the order specified. 


-of write output module to file #, Default is xeq. 


-r suppress relocation bits. This should not be specified if the output 
module is to be input to link or executed under a version of Idris 
that relocates commands on startup. 


-sb* if the symbol * is referenced, make it equal to the size of the bss 
area. 


-sd* if the symbol * is referenced, make it equal to the size of the data 
area. 


-stë if the symbol * is referenced, make it equal to the size of the text 
area, 


-tbf set text bias to the long integer ##. Default is location zero. 


-tf# round text size up by appending NUL bytes to the text section, to en- 
sure that there are at least # low-order binary zeroes in the result- 
ing value. Default is zero, í.e. no padding. 


=t suppress symbol table. This should not be specified if the output 
module is to be input to link. 


-u* enter the symbol * into the symbol table as an undefined public 
reference, usually to force loading of selected modules from a 
library. 


-x# specify placement in the output module of the input .text and .data 
sections. The 2-weighted bit of $ routes .text input, the t-weighted 
bit, .data. If either bit is set, the corresponding sections are put 
in the text segment output; otherwise, they go in the data segment. 
The default value used, predictably, is 2. 


The bss section is always assumed to follow the data section in all input 
files. Unless -bb## is given, the bss section will be made to follow the 
data section in the output file, as well. It is perfectly permissible for 
text and data sections to overlap, as far as link is concerned; the tar- 
get machine may or may not make sense of this situation (as with separate 
instruction and data spaces). 


The specified «files» are linked in order; if a file is in library for- 
mat, it is searched once from start to end. Only those library modules 
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are included which define public symbols for which there are currently 
outstanding unsatisfied references. Hence, libraries must be carefully 
ordered, or rescanned, to ensure that all references are resolved. By 
special dispensation, flags of the form "-1*" may be interspersed among 
<files>. These call for the corresponding libraries to be searched at the 
points specified in the list of files. No space may occur after the "-1", 
in this usage. 


File Format 


A relocatable object image consists of a header followed by a text seg- 
ment, a data segment, the symbol table, and relocation information. 


The header consists of an identification byte Ox99, a configuration byte, 
a short unsigned int containing the number of symbol table bytes, and six 
unsigned ints giving: the number of bytes of object code defined by the 
text segment, the number of bytes of object code defined by the data seg- 
ment, the number of bytes needed by the bss segment, the number of bytes 
needed for stack plus heap, the text segment offset, and the data segment 
offset. 


Byte order and size of all ints in the header are determined by the con- 
figuration byte. 


The configuration byte contains all information needed to fully represent 
the header and remaining information in the file. Its value val defines 
the following fields: ((val & 07) << 1) + 1 is the number of characters 
in the symbol table name field, so that values [0, 8) provide for odd 
lengths in the range [1, 15). If (val & 010) then ints are four bytes; 
otherwise they are two bytes. If (val & 020) then ints in the data seg- 
ment are represented least significant byte first, otherwise, most sig- 
nificant byte first; byte order is assumed to be purely ascending or 
purely descending. If (val & 040) then even byte boundaries are enforced 
by the hardware. If (val & 0100) then the text segment byte order is 
reversed from that of tne data segment; otherwise text segment byte order 
is the same. If (val & 0200) no relocation information is present in this 
file. 


The text segment is relocated relative to the text segment offset given in 
the header (usually zero), while the data segment is relocated relative to 
the data segment offset (usually the end of the text segment). Unless 
-bbé£ is given, the bss segment is relocated relative to the end of the 
data segment. 


Relocation information consists of two successive byte streams, one for 
the text segment and one for tne data segment, each terminated by a zero 
control byte. Control bytes in the range [1, 31] cause that many bytes in 
the corresponding segment to be skipped; bytes in the range [32, 63] skip 
32 bytes, plus 256 times the control byte minus 32, plus the number of 
bytes specified by the relocation byte following. 


All other control bytes control relocation of the next short or long int 


in the corresponding segment. If the i-weighted bit is set in such a con- 
trol byte, then a change in load bias must be subtracted from the int. 
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The 2-weighted bit is set if a long int is being relocated instead of a 
Short int. The value of the control byte right-shifted two places, ninus 
16, constitutes a "symbol code". 


A symbol code of 47 is replaced by a code obtained from the byte or bytes 
following in the relocation stream. If the next byte is less than 128, 
then the symbol code is its value plus 47. Otherwise, the code is that 
byte minus 128, times 256, plus 175 plus the value of the next relocation 
byte after that one. 


A symbol code of zero calls for no further relocation; 1 means that a 
change in text bias must be added to the item (short or long int); 2 
means that a change in data bias must be added; 3 means that a change in 
bss bias must be added. Other symbol codes call for the value of the sym- 
bol table entry indexed by the symbol code minus 4 to be added to the 
item, 


Each symbol table entry consists of a value int, a flag byte, and a name 
padded with trailing NULs. Meaningful flag values are 0 for undefined, 4 
for defined absolute, 5 for defined text relative, 6 for defined data 
relative, and 7 for defined bss relative. To this is added 010 if the 
symbol is to be globally known. If a symbol still undefined after linking 
has a non-zero value, link assigns the syubol a unique area, in the bss 
Segment, whose length is specified by the value, and considers the symbol 
defined. This occurs only if -d has not been given. 


RETURNS 
link returns success if no error messages are printed to STDOUT, that is, 
if no undefined symbols remain and if all reads and writes succeed; 
otherwise it returns failure, 


EXAMPLE 
To load the C program echo.o under Idris/S11: 


$ Link -1c.11 -t /lib/Crts.o echo.o 
with separate I/D spaces, for UNIX: 

f$ link -10.11 -rt -dbO /lib/Crts.o echo.o; taout 
or with read only text section for UNIX: 

$ link -le.11 -rt -dr13 /lib/Crts.o echo.o; taout 
And to load the 8080 version of echo under CP/M: 


A:línk -hrt -tb0x0100 a:chdr.o echo.o a:clíb.a a:mlib.a 


ALSO 
hex, lib, lord, rel 
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lord IX. Programming Utilities lord 


NAME 
lord - order libraries 


SINOPSIS 
lord -[c* d*^ i r*^ s] 


FUNCTION 
lord reads in a list of module names, with associated interdependencies, 
from STDIN, and outputs to STDOUT a topologically sorted list of module 
names such that, if at all possible, no module depends on an earlier 
module in the list, Each module is introduced by a line containing its 
name followed by a colon. Subsequent lines are interpreted as either: 


defs - things defined by the module, 
refs - things referred to by the module, or 
other stuff - other stuff. 


Refs and defs have the syntax given by one or more formats entered as 
flags on the command line. Each character of the format must match the 
corresponding character at the beginning of an input line; a ? will match 
any character except newline. If all the characters of the format match, 
then the rest of the input line is taken as a ref or def name. Thus, the 
format flag "-d0x?2??D " would identify as a valid def any line beginning 
with "Ox", four arbitrary characters and a "D ", so that the input line 
"Ox3ffOD inbuf" would be taken as a def named " inbuf", 


The flags are: 

-c®8 prepend the string * to the output stream, Implies -s. Each module 
name is output preceded by a space; the output stream is terminated 
with a newline. Hence, lord can be used to build a command line. 


-d* use the string * as a format for defs. 


-1 ignore other stuff. Default is to complain about any line not recog- 
nizable as a def or ref. 


-r* use the string * as a format for refs. 

-8 suppress output of defs and refs; output only module names in order. 
Up to ten formats may be input for defs, and up to ten for refs. 

If no -d flags are given, lord uses the default def formats: 
"0x22272777B ", "Ox?7727777D ", "Ox?2777277T ", "Ox????B ", "Ox?777D ", 
"Ox????T ". If no -r flags are given, lord uses the default ref formats: 
70x2222222?U " and "Ox????U ". These are compatible with the default out- 
put of rel. 

If there are circular dependencies among the modules, lord writes the name 


of the file that begins the unsorted list to STDERR, followed by the mes- 
sage "not completely sorted". In general, rearrangements are made only 
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lord .2- lord 
when necessary, so an ordered set of modules should pass through lord un- 
changed. 


RETURNS 
lord returns success if no error messages are printed, otherwise failure. 


EXAMPLE 
To create an ordered library of object modules under Idris: 


$ rel *.o | lord -c"lib libx.a -c" | sh 
To order a set of objects using UNIX nm: 
f$ nm *.o > nmlist 
$ lord < nmlist -c"ar r libx.a" | \ 
-d"??7????T " -d"??7???D " -d"27??7?B " -r"2227??U " | sh 


SEE ALSO 
lib, rel 
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II. Programming Utilities pt 


p! - parse C programs 


SYNOPSIS 


p1 -[a bf c e 1 m nf of r£ u] «fiie» 


FUNCTION 


p! is the parsing pass of the C compiler. It accepts a sequential file of 
lexemes from the preprocessor pp and writes a sequential file of flow 
graphs and parse trees, suitable for input to a machíne-dependent code 
generator p2. The operation of p! is largely independent of any target 
machine. The flag options are: 


-a 


-bê 


-e 


-o* 


-rë 


-u 


compile code for machines with separate address and data registers. 
This flag implies -r6 (because currently used only in conjunction 
with the MC68000 code generator). 


enforce storage boundaries according to #, which is reduced modulo 5. 
A bound of 0 leaves no holes in structures or auto allocations; a 
bound of ! (default) requires short, int and longer data to begin on 
an even bound; a bound of 2 is the same as 1, except that 4-8 byte 
data are forced to a multiple of four byte boundary; a bound of 3 is 
the same as 2, except that B byte data (doubles) are forced to a mul- 
tiple of eight byte boundary. 


ignore case distinctions in testing external identifiers for 
equality, and map all names to lowercase on output. By default, case 
distinctions matter. 


don't force loading of extern references that are declared but never 
defined or used in an expression. Default is to load all externs 
declared. 


take integers and pointers to be 4 bytes long. Default is 2 bytes. 


treat each struct/union as a separate name space, and require x.m to 
have x a structure with m one of its members. 


ignore characters after the first # in testing external identifiers 
for equality. Default 1s 7; maximum is 8, except that values up to 
32 are permitted for the VAX-11 code generator only. 


write the output to the file * and write error messages to STDOUT. 
Default is STDOUT for output and STDERR for error messages. 


assign no more than # variables to registers at any one time, where # 
is reduced modulo 7. Default is 3 register variables; values above 
3 are currently acceptable only for the MC68000 code generator (3 
data registers « 3 address registers maximum), and the VAX-11 code 
generator (6 registers maximum). 


take "string" as array of unsigned char, not array of char. 
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If <file> is present, it is used as the input file instead of the default 
STDIN. On many systems (other than Idris/UNIX), the -o option and <file> 
are mandatory because STDIN and STDOUT are interpreted as text files, and 
hence become corrupted. 


EXAMPLE 
p1 is usually sandwiched between pp and some version of p2, as in: 


pp ~x -o temp! file.c 
p! -o temp2 temp! 
p2.11 -o file.s temp2 


SEE ALSO 
PP 


BüGS 
p! can be rather cavalier about semicolons. 
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p2.80 II. Programming Utilities p2.80 


NANE 
p2.80 - generate code for 8080 C programs 


SYNOPSIS 
p2.80 -[ck o* p x£] <file> 


FUNCTION 
p2.80 is the code generating pass of the C compiler. It accepts a sequen- 
tial file of flow graphs and parse trees from pt and writes a sequential 
file of A-Natural statements, suitable for input to the A-Natural assem- 
bler, as.80. 


As much as possible, the compiler generates free-standing code; but for 
those operations which cannot be done compactly, it generates inline calls 
to a set of machine-dependent library routines. The 8080 runtime library 
is documented in Section IV of this manual. 


The flags are: 
ck enable stack overflow checking. 


-0* Write the output to the file * and write error messages to STDOUT, 
Default is STDOUT for output and STDERR for error messages. 


-p emit profiler calls on entry to each function. 


-xë Map the three virtual sections, for Functions (04), Literals (02), 
and Variables (01), to the two physical sections Code (bit is a one) 
and Data (bit is a zero). Thus, "-x4" is for separate I/D space, 
"-x6" is for ROM/RAM code, and "-x7" is for compiling tables into 
ROM. Default is 6. 


If <file> is present, it is used as the input file instead of the default 
STDIN. On many systems (other than Idris/UNIX), <file> is mandatory, 
because STDIN is interpreted as a text file, and hence becomes corrupted. 


Files output from p1 for use with the 8080 code generator should be 
generated with:  "-bO" to eliminate holes in structures and auto alloca- 
tion, and "-n8" for full length external names. A boundary of "-b1" (the 
default) is also acceptable if compact storage is less important than com- 
patibility with data structures on other machines, such as the PDP-11. 
Note that use of the p! flags "-b2", "-b3", or "-1" will produce bizarre 
behavior and incorrect code in p2.80, often with no meaningful diag- 
nostics, 


Wherever possible, labels in the emitted code each contain a comment which 
gives the source line from which the code immediately following obtains. 


EXAMPLE 
p2.80 usually follows pp and p1, as follows: 


pp -x -o temp! file.c 


p! -b0 -n8 -o temp2.80 temp! 
p2.80 -o file.s temp2 
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SEE ALSO 
as.80, pi 


BUGS 
Stack overflow checking is only approximate, since a calculation of the 
exact stack high water mark is not attempted. 


In any expression of the form expr++ or expr--, expr is evaluated twice, 
which can lead to surprises if expr contains side-effects. 
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II. Programming Utilities PP 


Pp - preprocess defines and includes 


SYNOPSIS 


pp -[e d*^ i# o* p? s? x 6] «files» 


FUNCTION 


pp is the preprocessor used by the C compiler, to perform #define, 
#include, and other functions signalled by a #, before actual compilation 
begins. It can be used to advantage, however, with most language proces- 
sors. The flag options are: 


~e don't strip out /* comments */ nor continue lines that end with V. 


-dë where * has the form namezdef, define name with the definition string 
def before reading the input; if -def is omitted, the definition is 
taken as "1", The name and def must be in the same argument, i.e., 
no blanks are permitted unless the argument is quoted, Up to ten 
definitions may be entered in this fashion. 


-i* change the prefix used with finclude «filename» from the default "" 
to the string *. Multiple prefixes to be tried in order may be 
specified, separated by the character '|'. 


-0* write the output to the file * and write error messages to STDOUT. 
Default is STDOUT for output and STDERR for error messages. On many 
systems (other than Idris/UNIX), the -o option is mandatory with -x 
because STDOUT is interpreted as a text fíle, and hence becomes cor- 
rupted. 


-p? change the preprocessor control character from '$' to the character 


-87 change the secondary preprocessor control character from '8' to the 
character ?. 


-x put out lexemes for input to the C compiler p1, not lines of text. 


-6 put out extra newlines and/or SOH ('\1') codes to keep source line 
numbers correct for UNIX/V6 compiler or ptc. 


pp processes the named files, or STDIN if none are given, in the order 
Specified, writing the resultant text to STDOUT. Preprocessor actions are 
described in detail in Section I of the C Programmers! Manual. 


The presence of a secondary preprocessor control character permits two 
levels of parameterization. For instance, the invocation 


pp -e -pê 
will expand define and ifdef conditionals, leaving all # commands and com- 
ments intact; invoking pp with no arguments would expand both @ and # 


commands. The flag -s# would effectively disable the secondary control 
character, 
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EXAMPLE 
The standard style for writing C programs is: 


/* name of program 
*/ 
#include 4std.h» 


#define MAXN 100 


COUNT things[MAXN]; 
etc. 


The use of uppercase only identifiers is not required by pp, but is 
Strongly recommended to distinguish parameters from normal program iden- 
tifiers and keywords. 


SEE ALSO 
pi, pto 


mus 
Unbalanced quotes ' or " may not occur in a line, even in the absenoe of 
the -x flag. Floating constants longer than 38 digits may compile incor- 
rectly, on some host machines. 
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NAME 
prof - produce execution profile 


SYWOPSIS 
prof -[a f +l nr s t +z] [<ofile>] [<pfiles>] 


FUNCTION 
prof correlates one or more files of statistics recorded during the execu- 
tion of a program with the symbol table of the corresponding executable 
file, and produces a report profiling the run. The statistics are con- 
tained in "profile" files of standard format. The <ofile> given on the 
command line is the program whose exeoution produced tne statistios. 


Flags are: 
-a sort output in increasing order of address. 


-f sort output in decreasing order of frequency of calls to each func- 
tion. 


+l include local symbols in output. By default, only global symbols are 
included. 


-n sort output in increasing order of symbol name. 
-r reverse tne default sense of the output sort. 
-8 suppress the default heading. 


-t sort output in decreasing order of time spent in each function. This 
is tne default sort key. 


+z include symbols in output for which no entries or execution time were 
recorded. By default, these are excluded. 


If no <ofile> is given, "xeq" is used as the object filename, If no 
<pfiles> are given, prof expects profiling data to come from the file 
"profil". However, if any filenames appear after «ofile» on the command 
line, they will be read for profiling data instead. If more than one file 
is given, prof will accumulate data from each in turn, and output a single 
report giving the totals from all data files read. Thus the results of 
several instrumented runs of a given program may be merged to reduce 
statistical error, Naturally, if <pfiles> are given <ofile> must be given 
as well. 


Profiling involves two statistics: counting the calls made to each funo- 
tion in a program, and recording what portion of execution time is spent 
inside each function. In its report, prof outputs one line for each text- 
relative symbol in «file» (subject to «l and «z), showing the syubol name, 
the percentage of total execution time spent in tne region between this 
symbol and the next higher one, time in this region in milliseconds, tne 
number of calls made directly to this symbol's address, and the average 
amount of time recorded per call. Also, prof treats the final location 
available for function entry counts as an overflow location, in which 
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calls are counted to all functions that could not be given a location of 
their own. If this count is non-zero, prof outputs it, with the name 
"other syms". 


Idris records execution time by periodically examining the PC of the ex- 
ecuting program, using its value to index an array whose elements cor- 
respond to the permissible range of the PC. The selected array element is 
then incremented. Function entry counts are maintained by calls to a 
counting routine, which every Whitesmiths C compiler can be made to output 
by specifying the flag -p to the code generator. A function must be thus 
instrumented for an entry count to be maintained for it. The counting 
routine itself is specified at link time, as part of the runtime startup 
code. 


RETURNS 
prof returns success if all input files are readable and consistent with 
their expected format. 


SEE ALSO 
The profile file format description is in Section III of the Idris 
Programmers' Manual, while the runtime initialization code used to profile 
under Idris is documented along with the Idris system interface, in Sec- 
tion III.a of this manual. The portable profiling setup functions are 
described in Section IV of the Idris Programmers’ Manual, and the machine- 
dependent function entry counting routine is described in Section IV of 
the current manual. 


BUGS 
Sampling errors may occur unless the scaling factor used to record the PC 
location is no larger than the smallest boundary on which an instruction 
may begin; that is, a given array element may overlap function bodies, 
and a PC caught in one function may be treated as if it were caught in 
another. prof does what it can to compensate, by dividing the value of an 
overlapping array element between the functions involved. 


This utility is currently provided for use only on Idris host systems, 
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II. Programming Utilities pto 


pte - Pascal to C translator 


SYNOPSIS 


pte -[o f k mẹ në o* r s$] <ifile> 


FUNCTION 


ptc is a program that accepts as input lines of Pascal text and produces 
as output a corresponding C program which is acceptable to the 
Whitesmiths, Ltd. C compiler. If <ifile> is present, it is taken as the 
Pascal program to translate; otherwise input is taken from STDIN. 


The flags are: 
-c pass comments through to the C program. 


-f set the precision for reals to single precision (float). Default is 
double, 


-k permit pointer types to be defined using type identifiers from outer 
blocks. Default is ISO standard, i.e., the type pointed to must be 
defined in the same type declaration as the pointer type definition. 


-af make # the number of bits in MAXINT excluding the sign bit, e.g., 
MAXINT becomes 32767 for -m15, 1 for -m|, etc. Default for MAXINT is 
32766 [sic]. Acceptable values for # are in the range [0 , 32). 
Declaring MAXINT greater than the size of a pointer (16 or 32) will 
give unprediotable results. On a target machine with 16-bit poin- 
ters, # should be leas than 16. 


Make # the number of significant characters in external names. 
Default is 8 character external names. 


-o* write the C program to the file * and diagnostics to STDOUT. Default 
is STDOUT for the C program and STDERR for diagnostics. 


-r turn off runtime array bounds checks. 


-8$ make # the number of bits in the maximum allowable set size, i.e., 
the size of all sets whose basetype is integer becomes the specified 
power of two. Acceptable values are in the range [0 , 32). Default 
is 8 (256 elementa). 


The CP/M operating system implementation, on the Intel 8080 and Zilog 
2/80, restricts the acceptable value for f to the range [0,16]; for max- 
imum portability, this restriction should be honored. 


Identifiers are mapped to uppercase to keep from conflicting with those 
declared as reserved words in C. Moreover, structure declarations may be 
produced that contain conflicting field declarations; and declarations 
are present for library functions that may mot be needed. All of these 
peccadillos are forgiven by the use of appropriate C compiler options. 
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RETURNS 
pto returns success if it produces no diagnostics. 

BOGS 
Complex set expressions can produce very long lines that are truncated by 
pp. 
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Il. Programming Utilities rel 


rel - examine object files 


SYNOPSIS 


rel-[dg i o s t u v) «files» 


FUNCTION 


rel permits inspection of relocatable object files, in standard format, 
for any target machine. Such files may have been output by an assembler, 
combined by link, or archived by lib. rel can be used either to check 
their size and configuration, or to output information from their symbol 
tables. 


The flags are: 


-4 output all defined symbols in each file, one per line. Each line 
contains the value of the symbol, a code indicating to what the value 
is relative, and the symbol name. Values are output as the number of 
digits needed to represent an integer on the target machine. Reloca- 
tion codes are: 'T' for text relative, 'D' for data relative, 'B' for 
bss relative, 'A' for absolute, or '?' for anything rel doesn't 
recognize. Lowercase letters are used for local symbols, uppercase 
for globals. 


-g print global symbols only. 


-i print all global symbols, with the interval in bytes between succes- 
sive symbols shown in each value field. Implies the flags -[d u v]. 


-o output symbol values in octal, Default is hexadecimal. 


-s display the sizes, in decimal, of the text segment, the data segment, 
the bss segment, and the space reserved for the runtime stack plus 
heap, followed by the sum of all the sizes. 


-t list type information for this file. For each object file the data 
output is: the size of an integer on the target machine, the target 
machine byte order, whether even byte boundaries are enforced by tne 
hardware, whether the text segment byte order is reversed from that 
of the data segment, and the maximum number of characters permitted 
in an external name. If the file is a library, then the type of 
library is output and the information above is output for each module 
in the library. 


-u list all undefined symbols in each file. If -d is also specified, 
each undefined symbol is listed with the code 'U'. The value of each 
symbol, if non-zero, is the space to be reserved for it at load time 
if it is not explicitly defined. 


-v sort by value; implies the -d flag above. Symbols of equal value are 
Sorted alphabetically. 


If no flags are given, the default is -[d u]; that is, all symbols are 
listed, sorted in alphabetical order on symbol name. If more than one of 
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the flags -[d s t u} is selected, then type information is output first, 
followed by segment sizes, followed by the symbol list specified with -d 
or =u, 


<files> specifies zero or more files, which must be in relocatable format, 
or standard library format, or UNIX/V6 library format, or UNIX/V7 library 
format. If more than one file, or a library, is specified, then the name 
of each separate file or module precedes any information output for it, 
each name followed by a colon and a newline; if -s is given, a line of 
totals is also output. If no «files? are specified, or if "=" is encoun- 
tered on the command line, xeq is used. 


RETURNS 
rel returns success if no diagnostics are produced, that is, if all reads 
are successful and all file formats are valid. 


EXAMPLE 
To obtain a list of all symbols in a module: 


% rel alloc.o 
Ox00000074T _alloc 
0x00000000U exit 
0x000001feT free 
Ox000000beT _nalloc 
0x00000000U _sbreak 
0x00000000U write 


SER ALSO 
lib, link, lord 
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III.a. 


Idria System Interface Library 


to 8080 Idris system 

Idris system subroutines 

compile and link C programs 
compile and link Pascal programs 
C runtime entry 

set up profiling at runtime 
program name 

close a file 

open an empty instance of a file 
terminate program execution 

set file read/write pointer 

call function on program exit 
capture interrupts 

open a file 

read from a file 

remove a file 

set system break 

create a unique file name 

write to a file 

execute a file with argument list 
execute a file with argument vector 


Interface III.a. Idris System Interface Library Interface 


MAME 
Interface - to 8080 Idris system 


FUNCTION 
Programs written in C for operation on the 8080 under Idris are translated 
into A-Natural according to the following specifications: 


external identifiers - may be written in both upper and lower case. The 
first eight letters must be distinct. Any underscore is left alone. 
An underscore is prepended to each identifier. 


function text - is normally generated into the .text section and is not to 
be altered or read as data. External function names are published 
via public declarations. 


literal data - such as strings and switch tables, are normally generated 
into the .text section. 


initialized data - are normally generated into the .data section. Exter- 
nal data names are published via public declarations. 


uninitialized declarations - result in a public reference, one instance 
per program file. 


function calls - are performed by 


1) moving arguments on the stack, right to left. Character data is 
sign-extended to integer, float is zero-padded to double. 


2) calling via "call fune", 
3) popping the arguments off the stack. 


Except for returned vaiue, the registers fa, bo, and hl, and the in- 
core pseudo registers c.r0 and c.r!, are undefined on return from a 
function call. All other registers are preserved. The returned 
value is in bc (char sign-extended to integer, integer, pointer to), 
or in c.r0 (long, float widened to double, double).  oc.r0 and o.r1 
are each eight-byte memory areas that are not preserved on a function 
call; o.r2, c.r3, and c.r! are each two-byte memory areas that must 
be preserved on a function call. 


stack frames - are maintained by each C function, using de as a frame 
pointer. On entry to a function, the call "call c.ents" will stack 
de and leave it pointing at tne stacked de, then stack c.r2, c.r3, 
and c.r!. Arguments are at l(de), 6(de), etc. and auto storage may 
be reserved on the stack at -7(de) on down. To return, the jump "jap 
c.rets" will use de to restore de, sp, c.r}, c.r3, and c.r2, then 
return. The previous sp is ignored, so the stack need not be 
balanced on exit, and none of the potential return registers are 
used. If it is not necessary to save or restore c.r2, o.r3, and 
c.rl, the call "call c.ent" and jump "jap c.ret" may be used instead. 
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data representation - integer is the same as short, two bytes stored less 
significant byte first. Long integers are stored as two short in- 
tegers, more significant short first. All signed integers are twos 
complement. Floating numbers are represented as for the PDP-11 
Floating Point Processor, four bytes for float, eight for double, and 
are stored as two or four short integers, in descending order of sig- 
nificance. 


storage bounds - no storage bounds need to be enforced.  Two-byte boun- 
daries may be enforced, inside structures and among automatic 
variables, to ensure data structure compatibility with machines such 
as the PDP-11, but boundaries stronger than this are not fully sup- 
ported by the stacking hardware; the compiler may generate incorrect 
code for passing long or double arguments if a boundary stronger than 
even is requested. 


module name - is not produced. 


SEE ALSO 
c.ent(IV), c.ents(IV), c.entx(IV), c.rO(IV), c.ret(IV), c.rets(IV) 
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NAME 
Conventíons - Idris system subroutines 


SYNOPSIS 
finciude <sys.h> 


FUNCTION 
All standard system library functions callable from C follow a set of 
uniform conventions, many of which are supported at compile time by in- 
cluding a standard header file, <sys.h>, at the top of each program. Note 
that this header is used in addition to the standard header <std.h>. The 
system header defines various system parameters and a useful macro or two. 


Herewith the principal definitions: 


DIRSIZE - 14, the maximum directory name size 
E2BIG - 7, the error codes returned by system calls 


EACCES - 13 
EAGAIN - 11 
EBADF - 9 
EBUSY - 16 
ECHILD - 10 
EDOM - 33 
EEXIST - 17 
EFAULT - 14 
EFBIG - 27 
EINTR - 4 
EINVAL - 22 
EIO- 5 
EISDIR - 21 
EMFILE - 24 
EMLINK - 31 
ENFILE - 23 
ENODEV - 19 
ENOENT - 2 
ENOEXEC - 8 
ENOMEM - 12 
ENOSPC - 28 
ENOTBLK - 15 
ENOTDIR - 20 
ENOTTY - 25 
ENXIO - 6 
EPERM - 1 
EPIPE - 32 
ERANGE - 34 
EROFS - 30 
ESPIPE - 29 
ESRCH - 3 
ETXTBSY - 26 
EXDEV - 18 


NAMSIZE - 64, the maximum filename size, counting NUL at end 
NSIG - 16, the number of signals, counting signal 0 

SIGALRM - 14, the signal numbers 

SIGBUS - 10 
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SIGDOM - 7 
SIGFPT - 8 
SIGHUP - 1 
SIGILIN 
SIGINT - 2 
SIGKILL - 9 
SIGPIPE - 13 
SIGQUIT - 3 
SIGRNG - 6 
SIGSEG - 11 
SIGSYS - 12 
SIGTERM - 15 
SIGTRC - 5 


The macro isdir(mod) is a boolean rvalue that is true if the mode mod, ob- 
tained by a getmod call, is that of a directory. Similarly isb1k(mod) 
tests for block special devices, and ischr(mod) tests for character 
special devices. 


III.a - 4 


080 III.a. Idris System Interface Library c80 


NAME 
c80 - compile and link C programs 


SYNOPSIS 
c80 -[f* of p* v +") «files» 


FUNCTION 
680 is an instantiation of the generio C driver described in Section II, 


configured to compile C (with filenames *.c) or as.80 (*.s) source files 
to object (*.0), and/or to link object files with the standard header and 
libraries to produce an executable file. 


Since a prototype file is a text file, it is easy to vary pathnames or 
flags for local usage. 


SEE ALSO 
as-80(II), c(II), po80, pa.80(II) 
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peso III.a. Idris System Interface Library po80 


NAME 
pe80 - compile and link Pascal programs 


SYNOPSIS 
po80 -[f* of p* v +#] «files? 


FUNCTION 
pe80 is an instantiation of the generic C driver described in Section II, 
configured to compile Pascal (with filenames *.p), Pascal compatible C 
(*.c), or as.80 (*.s) source files to object (*.0), and/or to link object 
files with the standard header and libraries to produce an executable 
file. 


Since a prototype file is a text file, it is easy to vary pathnames or 
flags for local usage. 


SEE ALSO 
e{II), c80, pte(II) 
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III.a. Idris System Interface Library crt 


Crt - C runtime entry 


SYNOPSIS 


link [/iib/Crtp.o] /lib/Crts.o <main.o> 


FUNCTION 


All Idris programs begin execution at the start of the .text section; 
Crts.o is the startup routine that maps an Idris invocation into the stan- 
dard C call to main. 


Idris passes exec arguments on the stack with ac on top, followed by 
av[0], av[1), etc., whereas main expects a return link on top, followed by 
ac, then a pointer to av[0]. Similarly, Idris expects a zero return from 
main (argument to exit) to signal success, whereas a boolean true 
(non-zero) is returned by C on success.  Crts.o makes the necessary 
changes ín both directions. 


If profiling is to be performed, Crtp.o is the routine that a) allocates a 
profile buffer by calling sbreak, b) turns on profiling, c) fields calls 
to c.count on entry to each profiled function, and d) writes the file 
profil on exit, suitable for processing by the Idris prof utility. To 
make addresses come out right for prof, Crtp must be loaded first among 
headers. It exits by falling through to the next code in line. 


ALSO 
Crtp 
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Crtp III.a. Idris System Interface Library Crtp 


NAME 
Crtp - set up profiling at runtime 


SYWOPSIS 
link /lib/Crtp.o /lib/Crts.o <main.o> /lib/libi.# 


FUNCTION 
Crtp.o is the startup routine that enables profiling to occur, by calling 
the portable C function _profil(), which sets up profiling buffer areas 
and requests the operating system to begin periodically recording the user 
PC location. Crtp.o also contains the function entry counting routine 
called by properly instrumented functions (compiled with the p2 option 
"-p"). The one-byte flag _penable, if non-zero, enables this routine to 
perform counting. Otherwise, entry counting is disabled. 


Finally, Crtp.o contains the parameters controlling how profiling is per- 
formed. These are stored as a standard profile file header, whose start 
is marked by the symbol  pheader. The two parameters most likely to be 
modified are the number of function entry counters to be maíntained, a 
Short int at _pheader+2, and the number of bytes of text that are to cor- 
respond to each element of the PC histogram, the fourth int counting from 
.pheader«l. Note that both of these are modified before being output in 
the profile header, where the first becomes the number of bytes occupied 
by entry counters, and the second becomes the binary fraction correspon- 
ding to the integer scaling factor originally given. By default, Crtp.o 
Provides 100 function entry counters and a resolution of 8 text bytes per 
histogram entry. 


Crtp.o must be the first module in the .text section of a program, and so 
must appear fírst on the link command line. 


EXAMPLE 
To set up 256 function entry counters, and 4 bytes of text per histogram 
entry, for a PDP-11 executable file: 


$ db11 -u progtt 
progi!: 11400T + 1340D + OB 


. pheader«2 ps 
pheader+2 100 


u 
256 


. pheader«10 ps 

Z pheadere10 8 
u 

4 


q 


Or to set up 400 entry counters and a scaling factor of 2 bytes per 
histogram entry, for a MC68000 executable file: 


f$ db68k -u prog68k 
prog68k: 13542T + 1544D + OB 
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Crtp 


. pheader«2 ps 

I pheader«2 100 
u 

400 


. pheader«16 pl 

L pheader«16 8 
u 

2 


2 


SEE ALSO 
The profile file format description is in Section III of the Idris 
Programmers’ Manual. The portable profiling setup functions are described 
in Section IV of the Idris Programmers! Manual, and the machine-dependent 
function entry counting routine is described in Section IV of the current 


manual. The profile post-processor prof is described in Section II of 
this manual. 


BUGS 
Because of the original UNIX V6 specification for the histogram scaling 


factor (retained here), a factor of 2 bytes of text per histogram entry is 
the smallest that can be specified. 
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.pname III.a. Idris System Interface Library .pname 


NAME 
.pname - program name 


SYNOPSIS 
TEXT *pname; 


FUNCTION 


.pname is the (NUL terminated) name by which the program was invoked, as 
Obtained from the command line argument zero. It overrides any name sup- 
plied by the program at compile time. 


It is used primarily for labelling diagnostic printouts. 
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olose III.a. Idris System Interface Library close 


MAME 
close - close a file 


SYNOPSIS 
ERROR close(fd) 
FILE fd; 


FUNCTION 
close closes the file associated with the file descriptor fd, making fd 
available for future open or create calls. 


RETURES 
close returns zero, if successful, or a negative number, which is tne 
Idris error return code, negated. 


EXAMPLE 
To copy an arbitrary number of files: 


while (0 < ac && O <= (fd = open(av[--ac], READ, 0))) 
{ 
while (0 < (n = read(fd, buf, BUFSIZE))) 


write(STDOUT, buf, n); 
close(fd); 
) 


SEE ALSO 
create, open, remove, uname 
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NAME 
create - open an empty instance of a file 


SYNOPSIS 
FILE create(fname, mode, rsize) 
TEXT *fname; 
COUNT mode; 
BYTES rsize; 


FUNCTION 

create makes a new file with name fname, if it did not previously exist, 
or truncates the existing file to zero length. An existing file has its 
permissions left alone; otherwise if the filename returned by uname is a 
prefix of fname, the (newly created) file is given restricted access 
(0600); if not, the file is given general access (0666). If (mode == 0) 
the file is opened for reading, else if (mode 1) it is opened for 
writing, else (mode == 2) of necessity and the file is opened for updating 
(reading and writing). 


rsize is the record size in bytes, which must be nonzero on many systems 
if the file is not to be interpreted as ASCII text. It is ignored by 
Idris, but should be present for portability. 


RETURNS 
create returns a file descriptor for the created file or a negative num- 
ber, which is the Idris error return code, negated. 


EXAMPLE 
if ((fd = create("xeq", WRITE, 1)) < 0) 
putstr(STDERR, "can't create xeq\n", NULL); 


SEE ALSO 
close, open, remove, uname 
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exit III.a. Idris System Interface Library exit 


NAME 
exit - terminate program execution 


SYNOPSIS 
VOID exit(success) 
BOOL success; 


FUNCTION 
exit calls all functions registered with onexit, then terminates program 
execution. If succeas is non-zero (YES), a zero byte is returned to the 
invoker, which is the normal Idris convention for successful termination. 
If success is zero (NO), a one is returned to the invoker. 


RETURNS 
exit will never return to the caller. 


EXAMPLE 
if ((fd = open("file", READ)) < 0) 


t 

putstr(STDERR, "can't open file\n", NULL); 
exit(NO); 

H 


SEE ALSO 
onexit 
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iseek III.a. Idris System Interface Library lseek 


NAME 
lseek - set file read/write pointer 


SYNOPSIS 
COUNT lseek(fd, offset, sense) 
FILE fd; 
LONG offset; 
COUNT sense; 


FUNCTION 

lseek uses the long offset provided to modify the read/write pointer for 
the file fd, under control of sense. If (sense == 0) the pointer is set 
to offset, which should be positive; if (sense 1) the offset is al- 
gebraically added to the current pointer; otherwise (sense 2) of 
necessity and the offset is algebraically added to the length of the file 
in bytes to obtain the new pointer. Idris uses only the low order 24 bits 
of the offset; the rest are ignored. 


The call lseek(fd, OL, 1) is guaranteed to leave the file pointer un- 
modified and, more important, to succeed only if lseek calls are both ac- 
ceptable and meaningful for the fd specified. Other lseek calls may ap- 
pear to succeed, but without effect, as when rewinding a terminal. 


RETURNS 
lseek returns the file descriptor if successful, or a negative number, 
which is the Idris error return code, negated. 


EXAMPLE 
To read a 512-byte block: 


BOOL getblock(buf, blkno) 
TEXT *buf; 
BYTES blkno; 
{ 
lseek(STDIN, (LONG) blkno << 9, 0); 
return (read(STDIN, buf, 512) != 512); 
) 
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onexit III.a. Idris System Interface Library onexit 


NAHE 
onexit - call function on program exit 


SYNOPSIS 
VOID (*onexit())(pfn) 
VOID (#(#pfn)())(); 


FUNCTION 
onexit registers the function pointed at by pfn, to be called on program 
exit. The function at pfn is obliged to return the pointer returned by 
the onexit call, so that any previously registered functions can also be 
called. 


RETURNS 
onexit returns a pointer to another function; it is guaranteed not to be 
NULL. 


EXAMPLE 
IMPORT VOID (*{*nextguy)())(), (#thisguy())(); 


if (Inextguy) 
nextguy s onexit(&thisguy); 


SEE ALSO 
exit, onintr 


BUGS 
The type declarations defy description, and are still wrong. 
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onintr III.a. Idris System Interface Library onintr 


NAME 
onintr - capture interrupts 


SYNOPSIS 
VOID onintr(pfn) 
VOID (*pfn)O; 


FUNCTION 
onintr ensures that the funotion at pfn is called on a broken pipe, or on 
the occurrence of an interrupt (DEL key) or hangup generated from the key- 
board of a controlling terminal. Any earlier call to onintr is overrid- 
den. 


The function is called with one integer argument, whose value is always 
zero, and must not return; if it does, a message is output to STDERR and 
an immediate error exit is taken. 


If (pfn == NULL) then these interrupts are disabled (turned off). Any 
disabled interrupts are not, however, turned on by a subsequent call with 
pfn not NULL. 


RETURNS 
Nothing. 


EXAMPLE 
A coumon use of onintr is to ensure a graceful exit on early termination: 


onexit (&rmtemp) 5 
onintr(&exit); 


VOID rmtemp() 

1 

remove (uname()) ; 
Still another use is to provide a way of terminating long printouts, as in 
an interactive editor: 

while (lenter(docmd, NULL)) 

putstr(STDOUT, "?Wn", NULL); 

VOID doeud() 

t 

onintr(&leave); 


SEE ALSO 
onexit 
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open III.a. Idris System Interface Library open 


NAME 
open - open a file 


SYNOPSIS 
FILE open(fname, mode, rsize) 
TEXT *fname; 
COUNT mode; 
BYTES rsize; 


FUNCTION 
open opens a file with name fname and assigns a file descriptor to it. If 
(mode == 0) the file is opened for reading, else if (mode == 1) it is 
opened for writing, else (mode == 2) of necessity and the file is opened 
for updating (reading and writing). 


rsize is the record size in bytes, which must be nonzero on many systems 
if the file is not to be treated as ASCII text. It is ignored by Idris, 
but should be present for portability. 


open returns a file descriptor for the opened file or a negative number, 
which is the Idris error return code, negated. 


if ((fd = open("xeq", WRITE, 1)) < 0) 
Putstr(STDERR, "can't open xeq\n", NULL); 


SEE ALSO 
close, create 
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read III.a. Idris System Interface Library read 


NAME 
read - read from a file 


SYNOPSIS 
COUNT read(fd, buf, size) 
FILE fd; 
TEXT *buf; 
BYTES size; 


FUNCTION 
read reads up to size characters from the fíle specified by fd into the 
buffer starting at buf. 


RETURNS 
If an error occurs, read returns a negative number which is the Idris er- 
ror code, negated; if end of file is encountered, read returns zero; 
otherwise the value returned is between 1 and size, inclusive. When 
reading from a disk file, size bytes are read whenever possible. 


EXAMPLE 
To copy a file: 


while (0 < (n = read(STDIN, buf, BUFSIZE))) 
write(STDOUT, buf, n); 


SEE ALSO 
write 
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remove III.a. Idris System Interface Library remove 


NAME 
remove - remove a file 


SYNOPSIS 
FILE remove(fname) 
TEXT *fname; 


FUNCTION 
remove deletes the file fname from the Idris directory structure. If no 
other names link to the file, the file is destroyed. If the file is 
opened for any reason, however, destruction will be postponed until the 
last close on the file. 


If the file is a directory, remove will not attempt to remove it. 


RETURNS 
remove returns zero, if successful, or a negative number, which is the 
Idris error return code, negated. 


EXAMPLE 
if (remove ("temp.c™) < 0) 
putstr(STDERR, "can't remove temp file\n", NULL); 


SEE ALSO 
create 
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sbreak IlI.a. Idris System Interface Library sbreak 


NAME 
Sbreak - set system break 


SYNOPSIS 
TEXT *sbreak(size) 
BYTES size; 


FUNCTION 
Sbreak moves the system break, at the top of the data area, algebraically 
up by size bytes, rounded up as necessary to placate memory management 
hardware. 


RETURNS 
If successful, sbreak returns a pointer to the start of the added data 
area; otherwise the value returned is NULL. 


EXAMPLE 
if (!(p = sbreak(nsyms * sizeof (symbol)))) 


{ 

Putstr(STDERR, "not enough room!\n"™, NULL); 
exit(NO); 

} 
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uname III.a. Idris System Interface Library uname 


NAME 
uname - create a unique file name 


SINOPSIS 
TEXT *uname() 


FUNCTION 

uname returns a pointer to the start of a NUL terminated name which is 
&uaranteed not to conflict with normal user filenames. The name is, in 
fact, unique to each Idris process, and may be modified by a suffix, so 
that a family of process-unique files may be dealt with. The name may be 
used as the first argument to a create, or subsequent open, call, so long 
as any such files created are removed before program termination. It is 
considered bad manners to leave scratch files lying about. 


RETURMS 
uname returns the same pointer on every call during a given program in- 
vocation. It takes the form "/tmp/t#####" where ##### is the processid in 
octal. The pointer will never be NULL. 


if ((fd = create(uname(), WRITE, 1)) < 0) 
putstr(STDERR, "can't create sort temp\n", NULL); 


SEE ALSO 
close, create, open, remove 


BUGS 
A program invoked by the exec system call, without a fork, inherits the 
Idris processid used to generate unique names. Collisions can occur if 
files so named are not meticulously removed. 
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write III.a. Idris System Interface Library write 


HAME 
write - write to a file 
SYNOPSIS 
COUNT write(fd, buf, size) 
FILE fd; 


TEXT *buf; 
BYTES size; 


FUNCTION 
Write writes size characters starting at buf to the file specified by fd. 


RETURNS 
If an error occurs, write returns a negative number which is the Idris er- 
ror code, negated; otherwise the value returned should be size. 


EXAMPLE 
To copy a file: 


while (0 < (n = read(STDIN, buf, size))) 
write(STDOUT, buf, n); 


SEE ALSO 
read 
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III.a. Idris System Interface Library xecl 


NAME 


xecl - execute a file with argument list 


SYNOPSIS 


COUNT xecl(fname, sin, sout, flags, 30, $1, ..., NULL) 
TEXT *fname; 
FILE sin, sout; 
COUNT flags; 
TEXT *s0, #51, ... 


FUNCTION 


Xecl invokes the program file fname, connecting its STDIN to sin and 
STDOUT to sout and passing it the string arguments s0, si, ... If 
(1(flags & 3)) fname is invoked as a new process; xecl will wait until 
the command has completed and will return its status to the calling 
program. 1f (flags & 1) fname is invoked as a new process and xecl will 
not wait, but will return the processid of the child. If (flags & 2) 
fname is invoked in place of the current process, whose image is forever 
gone. In this case, xecl will never return to the caller. 


To the value of flags may be added a 4 if the processing of interrupt and 
quit signals for fname is to revert to system handling. The value of 
flags may also be incremented by 8 if the effective userid is to be made 
the real userid before fname is executed. If sin is not equal to STDIN, 
or if sout is not equal to STDOUT, the file (sin or sout} is closed before 
xecl returns. 


If fname does not contain a //^, then xeol will search an arbitrary series 
of directories for the file specified, by prepending to fname each path 
specified by the global variable paths before trying to execute it. 
paths is of type pointer to TEXT, and points to a NUL terminated series 
of directory paths separated by '|'s. 


1f the file eventually found has execute permission, but is not in ex- 
ecutable format, /bin/sh is invoked with the current prefixed version of 
fname as its first argument and, following fname, an argument vector com- 
posed of $0, sl, ... 


RETURNS 


If fname cannot be invoked, xecl will fail. If (l(flags & 3)) xecl 
returns YES if the command executed successfully, otherwise NO; if (flags 
& 1) xecl returns the id of the child process, if one exists, otherwise 
zero; if (flags & 2) xecl will never return to the caller. 


In all cases, if fname cannot be executed, an appropriate error message is 
written to STDERR. 


EXAMPLE 


if (!xecl(pgm, STDIN, create(file, WRITE), 0, f1, f2, NULL)) 
putstr(STDERR, pgm, " failed\n", NULL); 
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xeov III.a. Idris System Interface Library xecv 


NAME 
Xeov - execute a file with argument vector 
SYNOPSIS 
COUNT xecv(fname, sin, sout, flags, av) 
TEXT *fname; 


FILE sin, sout; 
COUNT flags; 
TEXT "av; 


FUNCTION 
Xecv invokes the program file fname, connecting its STDIN to sin and 
STDOUT to sout and passing it the string arguments specified in the NULL 
terminated vector av. Its behavior is otherwise identical to xecl. 


SEE ALSO 
xecl 
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II.b. 


Interface 
Conventions 
c 


pe 
1d 


CP/M System Interface Library 


to CP/M system 

CP/M system subroutines 
compiling C programs 
compiling Pascal prograus 
linking a C program 

C runtime entry 

setup for main call 

program name 

close a file 

call CP/M or CDOS system 
open an empty instance of a file 
terminate program execution 
set file read/write pointer 
call function on program exit 
capture interrupts 

open an existing file 

read characters from a file 
remove a file 

set system break 

create a unique file name 
write characters to a file 


Interface III.b. CP/M System Interface Library Interface 


NAME 
Interface - to CP/M system 


FUNCTION 
Programs written in C for operation on the 8080 under CP/M are translated 
into A-Natural according to the following specifications: 


external identifiers - may be written in both upper and lower case. The 
first eight letters must be distinct. Any underscore is left alone. 
An underscore is prepended to each identifier. 


function text - is normally generated into the .text section and is not to 
be altered or read as data. External function names are published 
via public declarations. 


literal data - such as strings and switch tables, are normally generated 
into the .text section. 


initialized data - are normally generated into the .data section. Exter- 
nal data names are published via public declarations. 


uninitialized declarations - result in a public reference, one instance 
per program file. 


function calls - are performed by 


1) moving arguments on the stack, right to left. Character data is 
sign-extended to integer, float is zero-padded to double. 


2) calling via "call fune", 
3) popping the arguments off the stack. 


Except for returned value, the registers fa, be, and hi, and the in- 
core pseudo registers c.rÜ and c.r1, are undefined on return from a 
function call. All other registers are preserved. The returned 
value is in be (char sign-extended to integer, integer, pointer to), 
or in c.r (long, float widened to double, double). c.r0 and ceri 
are each eight-byte memory areas that are not preserved on a function 
call; c.r2, c.r3, and c.ri are each two-byte memory areas that must 
be preserved on a function call. 


stack frames - are maintained by each C function, using de as a frame 
pointer. On entry to a function, the call "call c.ents" will stack 
de and leave it pointing at the stacked de, then stack o.r2, o.r3, 
and c.rl. Arguments are at 4(de), 6(de), etc. and auto storage may 
be reserved on the stack at -7(de) on down. To return, the jump "jmp 
c.rets" will use de to restore de, sp, c.ri, c.r3, and c.r2, then 
return. The previous sp is ignored, so the stack need not be 
balanced on exit, and none of the potential return registers are 
used. If it is not necessary to save or restore c.r2, c.r3, and 
C.ri, the call "call c.ent" and jump "jmp c.ret" may be used instead. 
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Interface -2- Interface 


data representation - integer is the same as short, two bytes stored less 
significant byte first. Long integers are stored as two short in- 
tegers, more significant short first. All signed integers are twos 
complement. Floating numbers are represented as for the PDP-11 
Floating Point Processor, four bytes for float, eight for double, and 
are stored as two or four short integers, in descending order of sig- 
nificance. 


storage bounds - np storage bounds need to be enforced. ‘Two-byte boun- 
daries may be enforced, inside structures and among automatic 
variables, to ensure data structure compatibility with machines such 
as the PDP-11, but boundaries stronger than this are not fully sup- 
ported by the stacking hardware; the compiler may generate incorrect 
code for passing long or double arguments if a boundary stronger than 
even is requested. 


module name - is not produced. 


SEE ALSO 
c.ent(IV), c.ents(IV), c.entx(IV), c.rO(IV), c.ret(IV), c.rets(IV) 
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Conventions III.b. CP/M System Interface Library Conventions 


MAME 
Conventions - CP/M system subroutines 


SYNOPSIS 
#include <cpm.h> 


FUNCTION 
All standard system library functions callable from C follow a set of 
uniform conventions, many of which are supported at compile time by in- 
cluding a system header file, <cpm.h>, at the top of each program. Note 
that this header is used in addition to the standard header <std.h>. The 
system header defines various system parameters and a useful macro or two. 


Herewith the prinoipal definitions: 


CTRLZ - 032, ctl-Z for text end of file 
EOF - 1, end of file from CP/M read 


FAIL - -1, standard failure return code 
MCREATE , copen modes 

MOPEN - 1 

MREMOVE - 2 

MWRITE - 4 


SYSBUF - 0x80, location of CP/M buffer 
CRESET - 0, CP/M system call codes 


CRDCON - 1 
CWRCON - 2 
CRDRDR - 3 
CWRPUN - 4 
CWRLST - 5 
CDCIO - 6 
CGIOST - 7 
CSIOST - 8 
CPRBUF - 9 
CRDBUF - 10 
CICRDY - 11 
CLFTHD - 12 
CINIT - 13 
CLOGIN - 14 
COPEN - 15 
CCLOSE - 16 
CSRCH - 17 
CSRCHN - 18 
CDEL - 19 
CREAD - 20 
CWRITE - 21 
OMAKE - 22 
CRENAME - 23 
CILOGIN - 2! 
CIDRNO - 25 
CSETAD - 26 
CIALLOC - 27 
CWPROT - 28 
CGETVEC - 29 
CSETFA - 30 
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Conventions -2- Conventions 


CGETPAR - 31 
CGSUSER - 32 
CRREAD - 33 
CRWRITE = 34 
CFSIZE - 35 
CSETRR - 36 
CDRESET - 37 
CRZWRIT - 40 
WOPEN - !, the WCB flags 
WDIRT - 2 
WSTD - 4 
WCR - 010 
WUSED - 020 
LST - -4, the device codes 
PUN - -3 
RDR - -2 
CON - -1 
SEE ALSO 


CP/M or CDOS Manual 
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NAME 
c - compiling C programs 


SINOPSIS 
A:submit c sfile 


FUNCTION 
C is an indirect command file that causes a C source file to be compiled 
and assembled. It does so by invoking the compiler passes and the assem- 
bler in the proper order, then deleting the intermediate files. 


The C source file is at sfile.c, where sfile is the name typed in the sub- 
mit line. The relocatable image from the assembler is put at sfile.o. 


EIAMPLE 
To compile test.c: 


Arsubmit c test 


SEE ALSO 
id, pe 


FILES 
sfile.tm? 


BUGS 


There should be some way to pass the -m flag to pl, or some of the myriad 
flags acceptable to pp, other than by modifying the command file proper. 
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NAME 
pe - compiling Pascal programs 


SYNOPSIS 
Arsubmit pe sfile 


FUNCTION 
pe is an indirect command file that causes a Pascal source file to be com- 
piled and assembled. It does so by invoking the compiler passes and the 
assembler in the proper order, then deleting the intermediate files. 


The Pascal source file is at sfile.p, where sfile is the name typed in the 
submit line. The relocatable image from the assembler is put at sfile.o. 


EXAMPLE 
To compile test.p: 


Arsubmit pe test 


SER ALSO 
e, 1d 


FILES 
sfile.tm? 


BUGS 


There should be some way to pass flags to ptc, other than by modifying the 
command file proper. 
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ld - linking a C program 


SYNOPSIS 


A:submit 1d ofile 


FUNCTION 


Programs written in C must be linked with certain object modules that im- 
plement the standard C runtime environment. The ld coumand script invokes 
the link program, including the standard object header file, the object 
file ofile, and any libraries in the correct order, and produces the ex- 
ecutable image xeq.com. 


The standard object header gets control when xeq.com is run. It calls the 
function main(), described in the system library, which reads in a com- 
mand line, redirects the standard input and output as necessary, calls the 
user provided main(ac, av) with the command arguments, and passes the 
value returned by main on to exit(). All of this malarkey can be circum- 
vented if file contains a defining instance of _main(). 


ofile must de a standard object file produced by the assembler, or by an 
earlier (partial binding) invocation of link. The assembler accepts 
either the output of the C code generator p2 or assembler source that 
satisfies the interface requirements of C, as described earlier under In- 
terface. The important thing is that the function main(), or _main(), be 
defined somewhere among these files, along with any other modules needed 
and not provided by the standard C library. 


To compile and run the program echo.o: 


Ai:submit o echo 
A:submit ld echo 
A:xeq hello world! 
hello world! 


ALSO 
C, pe 
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NAME 
ehdr - C runtime entry 


SYNOPSIS 
link -htr -tb0x100 a:chdr.o «files» 


FUNCTION 
All CP/M programs begin execution at location 0x100;  chdr.o is the 
Startup routine, linked at this address, that sets the stack to the 
address stored at location 6, then calls _main(). 


Included in the chdr module is the C callable interface function cpm(), 
plus several internal functions that isolate 8080 machine dependencies. 


SEE ALSO 
.main, cpm 
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mein II.b. CP/M System Interface Library main 


_main - setup for main call 


STNOPSIS 


BOOL main() 


FUNCTION 


_main is the function called whenever a C program is started. It parses 
the command line at 0x80 (in the program base) into argument strings, 
redirects STDIN and STDOUT as specified in the command line, then calls 
main. 


The command line is interpreted as a series of strings separated by 
spaces. If a string begins with a '4^, the remainder of the string is 
taken as the name of a file to be opened for reading text and used as the 
standard input, STDIN. If a string begins with a ‘>’, the remainder of 
the string is taken as the name of a file to be created for writing text 
and used as the standard output, STDOUT. All other strings are taken as 
argument strings to be passed to main. The command name, av[0], is taken 
from pname. 


Note that the argument strings remain in the default record buffer begin- 
ning at 0x80 in the program base, which is never used by other C interface 
routines. 


EXAMPLE 


To avoid the loading of main and all the the file I/O code it calls on, 
one can províde a substitute main instead: 


BOOL main() 
t 


program body» 
} 


main returns the boolean value obtained from the main call, which is then 
passed to exit. 


SEE ALSO 


.pname, cpm, exit 
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.posme III.b. CP/M System Interface Library panne 


NAME 
.pname - program name 


SYNOPSIS 
TEXT * pname; 


FUNCTION 
.pname is the (NUL terminated) name by which the program was invoked, at 
least as anticipated at compile time. If the user program provides no 
definition for _pname, a library routine supplies the name "error", since 
it is used primarily for labelling diagnostic printouts. 


Argument zero of the command line is set equal to _pname. 


SEE ALSO 
main 


III.b - 10 


olose III.b. CP/M System Interface Library close 


MAME 
close - close a file 


SYNOPSIS 
FILE close(fd) 
FILE fd; 


FUNCTION 
Close closes the file associated with the file descriptor fd, making the 
fd available for future open or create calls. If the file was written to 
or created, close ensures that the last record is written out and the 
directory entry properly closed. 


RETURNS 
close returns the now useless file descriptor, if successful, or -1. 


EXAMPLE 
To copy an arbitrary number of files: 


while (0 «- (fd - getfiles(&ac, &av, STDIN, -1))) 
t 
while (0 « (n = read(fd, buf, BUFSIZE))) 
write(STDOUT, buf, n); 
close(fd); 
} 


SEE ALSO 
create, open, remove, uname 
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opm III.b. CP/M System Interface Library opa 


NAME 
cpm - call CP/M or CDOS system 
SINOPSIS 
COUNT cpm(be, de, hl) 
COUNT be; 


TEXT *de, "nl; 


FUNCTION 
cpu is the C callable function that permits arbitrary calls to be made on 
CP/M or CDOS. It loads its arguments into registers bo, de, and hl, then 
performs a call to absolute location 5. The function to be performed is 
specified by the less significant byte of be, i.e., the c register; 
typically de contains a word integer or a pointer. hl is used only by 
CDOS, and then only on rare ocoasions. 


RETURNS 
epm returns the a register returned by the CP/M call, sign extended to a 
word integer. 


To read a line from the console: 
buf(0) = 125; 


Cpu(CRDBUF, buf, 0); 
epm(CWRCON, ^wn', 0); 
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oreate III.b. CP/M System Interface Library create 


NAME 
create - open an empty instance of a file 
STNOPSIS 
FILE ereate(name, mode, rsize) 
TEXT "nane; 
COUNT mode; 


BYTES rsize; 


FUNCTION 
create makes a new file of specified name, if it did not previously exist, 
or truncates the existing file to zero length. If (mode == 0) the file is 
opened for reading, else if (mode == 1) it is opened for writing, else 
(mode -- 2) of necessity and the file is opened for updating (reading and 
writing). This mode information is largely ignored, however. 


If (rsize is zero), carriage returns and NULs are deleted on input, a 
ctl-Z is treated as an end of file, a carriage return is injected before 
each newline on output, and a ctl-Z is appended to the data in a partially 
filled last record. If (rsize t= 0) data is transmitted unaltered. 


Filenames take the general form x:name.typ, where x is the disk desig- 
nator, name is the eight-character filename, and typ its three-character 
type. If x: is omitted, it is taken as the disk logged in on the first 
call to create, open, or remove; a missing name or typ is taken as all 
blanks. Letters are forced uppercase. 


The four physical devices con:, rdr:, pun:, and lst: are also accepted as 
filenames. Reading from pun: or lst: gives an instant end of file, while 
writing to rdr: sends all bytes to hell with no complaint. 


RETURNS 
create returns a file descriptor for the created file or -1. 


EXAMPLE 
if ((fd = create("xeq", WRITES, 1)) < 0) 
write(STDERR, "can't create xeq\n", 17); 


SEE ALSO 
Close, open, remove, uname 
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exit III.b. CP/M System Interface Library exit 


NAME 
exit - terminate program execution 


SYNOPSIS 
VOID exit(success) 
BOOL success; 


FUNCTION 
exit calls all functions registered with onexit, then terminates program 
execution. success is ignored. 


RETURNS 
exit will never return to the caller. 


EXAMPLE 
if ((fd © open("file", READ)) < 0) 
{ 


write(STDERR, "can't open file\n", 16); 
exit(NO); 


onexit 
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lseek III.b. CP/M System Interface Library lseek 


MAME 
lseek - set file read/write pointer 


SYNOPSIS 
COUNT lseek(fd, offset, sense) 
FILE fd; 
LONG offset; 
COUNT sense; 


FONCTION 

lseek uses the long offset provided to modify the read/write pointer for 
the file fd, under control of sense. If (sense == 0) the pointer is set 
to offset, which should be positive; if (sense == 1) the offset is al- 
gebraically added to the current pointer; otherwise (sense == 2) of 
necessity and the offset is algebraically added to the length of the file 
in bytes to obtain the new pointer. The system uses only the low order 31 
bits of the offset; the sign is ignored. 


lseek returns zero if successful, or -1. 


EXAMPLE 
To read a 512-byte block: 


BOOL getblock(buf, blkno) 
TEXT *buf; 
BYTES blkno; 
t 
lseek(STDIN, (long) blkno << 9, 0); 
return (read(STDIN, buf, 512) t= 512); 
H 


The length of the file is taken as 128 times the total number of records, 
even if a text file is terminated early with a otl-Z. 
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onexit III.b. CP/M System Interface Library onexit 


NAME 
onexit - call function on program exit 


SYNOPSIS 
VOID (*onexit())(pfn) 
VOID (*(5pfn)O) 05 


FUNCTION 
onexit registers the function pointed at by pfn, to be called on program 
exit. The function at pfn is obliged to return the pointer returned by 
the onexit call, so that any previousiy registered functions can also be 
called. 


RETURNS 
onexit returns a pointer to another function; it is guaranteed not to be 
NULL. 


EXAMPLE 
IMPORT VOID (*(*nextguy)())(), (#thisguy()) Os 


if (Inextguy) 
nextguy = onexit(&thisguy); 


SEE ALSO 
exit 


Boss 
The type declarations defy description, and are still wrong. 
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onintr III.b. CP/M System Interface Library onintr 


NAME 
onintr - capture interrupts 


SYHOPSIS 
VOID onintr(pfn) 
VOID (*pfn)(); 


FUNCTION 


onintr ensures that the function at pfn is called on a keyboard interrupt, 
usually caused by a DEL key typed during terminal input or output. (Under 


DOS on the 8086, a CTL-BREAK also serves this function.) Any earlier call 
to onintr is overridden. 


The function is called with one integer argument, whose value is always 
zero, and must not return; if it does, an immediate error exit is taken. 


If (pfn 


NULL) then these interrupts are disabled (turned off). 


RETURNS 
Nothing. 


EXAMPLE 
A common use of onintr is to ensure a graceful exit on early termination: 


onexit(&rmtemp); 
onintr(&kexit); 


VOID rmtemp() 

{ 

remove (uname()); 

} 
Still another use is to provide a way of terminating long printouts, as in 
an interactive editor: 


while (lenter(doomd, NULL)) 
putstr(STDOUT, "?n", NULL); 


VOID docnd() 
{ 
onintr(&leave); 


SEE ALSO 
onexit 
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open III.b. CP/M System Interface Library open 


NAME 
open - open an existing file 


SYNOPSIS 
FILE open(name, mode, rsize) 
TEXT "name; 
COUNT mode; 
BYTES rsize; 


FUNCTION 
open associates a file descriptor with an existing file. If (mode == 0) 
the file is opened for reading, else if (mode == 1) it is opened for 
writing, else (mode =: 2) of necessity and the file is opened for updating 
(reading and writing). This mode information is largely ignored, however. 


If (rsize == zero), carriage returns and NULs are deleted on input, a 
ctl-Z is treated as an end of file, a carriage return is injected before 
each newline on output, and a ctl-Z is appended to the data in a partially 
filled last record. If (rsize {= 0) data is transmitted unaltered. 


Filenames take the general form x:name.typ, where x is the disk desig- 
nator, name is the eight-character filename, and typ its three-character 
type. If x: is omitted, it is taken as the disk logged in on the first 
call to create, open, or remove; a missing name or typ is taken as all 
blanks. Letters are forced uppercase. 


The four physical devices con:, rdr:, pun:, and Ist: are also accepted as 
filenames. Reading from pun: or lst: gives an instant end of file, while 
writing to rdr: sends all bytes to hell with no complaint. 


RETURES 
open returns a file descriptor for the file or -1. 


EXAMPLE 
if ((fd = open("xeq", WRITES, 1)) < 0) 
write(STDERR, "can't open xeq\n", 15); 


SEE ALSO 
close, create, remove, uname 
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read III-b. CP/M System Interface Library read 


NAME 
read - read charaoters from a file 


SYNOPSIS 
COUNT read(fd, buf, size) 
FILE fd; 
TEXT *buf; 
BYTES size; 


FUNCTION 
read reads up to size characters from the file specified by fd into the 
buffer starting at buf. If the file was created or opened with (rsize == 
0) carriage returns and NULs are discarded on input. 


Reading from pun: or lst: always gives a count of zero. 


If the console is read, DEL at the start of a line causes an interrupt, to 
be processed as specified by onintr. 


RETURNS 
If an error occurs, read returns -1; if end of file is encountered, read 
returns zero; otherwise the value returned is between 1 and size, inclu- 
sive. 


EIAMPLE 
To copy a file: 


while (0 « (n = read(STDIN, buf, BUFSIZE))) 
write(STDOUT, buf, n); 


SEE ALSO 
onintr, write 
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remove III.b. CP/M System Interface Library 
RAME 
remove - remove a file 
SYNOPSIS 
FILE remove (fname) 
TEXT *fname; 


FUNCTION 
remove deletes tne file fname fron the filesystem. 


RETURNS 
remove returns zero, if successful, or -1. 


if (remove("temp.c") < 0) 
write(STDERR, "can't remove temp file\n", 23); 
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abreak III.b. CP/M System Interface Library sbreak 


NAME 
sbreak - set system break 


SYNOPSIS 
TEXT *sbreak(size) 
BYTES size; 


FUNCTION 
sbreak moves the system break, at the top of the data area, algebraically 
up by size bytes. 


RETURNS 
If successful, sbreak returns a pointer to the start of the added data 
area; otherwise the value returned is NULL. 


if (I(p = sbreak(nsyms * sizeof (symbol)))) 
{ 


weite(STDERR, "not enough room!\n", 17); 
exit(NO); 
) 


BUGS 
The stack is assumed to líe above the data area, so sbreak will return a 
NULL if the new system break lies above the current stack pointer; this 
may not be desirable behavior on all memory layouts. 
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uname III.b. CP/M System Interface Library uname 


NAME 
uname - create a unique file name 


SYNOPSIS 
TEXT *uname() 


FUNCTION 

uname returns a pointer to the start of a NUL-terminated name which is 
likely not to conflict with normal user filenames. The name may be 
modified by a letter suffix, so that a family of process-unique files may 
be dealt with. The name may be used as the first argument to a create, or 
Subsequent open, call, so long as any such files created are removed 
before program termination. It is considered bad manners to leave scratch 
files lying about. 


RETURNS 
uname returns the same pointer on every call, which is currently the 
string "ctempc.". The pointer will never be NULL. 


EXAMPLE 
if ((fd = create(uname(), WRITE, 0)) < 0) 
Write(STDERR, "can't create sort temp\n", 23); 


SEE ALSO 
Close, create, open, remove 
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write 


CP/M System Interface Library write 


NAME 
write - write characters to a file 


SYNOPSIS 
COUNT write(fd, buf, size) 
FILE fd; 
TEXT "buf; 
COUNT size; 


FUNCTION 
write writes size characters starting at buf to the file specified by fd. 
If the file was created or opened with (rsize 0), each newline output 
is preceded by a carriage return. Moreover, a otl-Z is appended to a file 
that does not end on a record boundary. 


RETURNS 
If an error occurs, write returns -1; otherwise the value returned should 


be size. Writing to rdr: does nothing, but returns size as if it did 
everything. 


Characters typed at the console are inspected during write calls; typing 
a DEL causes an interrupt, to be processed as specified by onintr. 


EXAMPLE 
To copy a file: 


while (0 < (n = read(STDIN, buf, size))) 
write(STDOUT, buf, n); 


SEE ALSO 
onintr, read 
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Interface XII.oc. ISIS-II System Interface Library Interface 


NAME 
Interface - to ISIS-II system 


FUNCTION 
Programs written in C for operation on the 8080 under ISIS-II are trans- 
lated into A-Natural according to the following specifications: 


external identifiers ~ may be written in both upper and lower case. The 
first eight letters must be distinct. Any underscore is ieft alone. 
An underscore is prepended to each identifier. 


function text - is normally generated into the .text section and is not to 
be altered or read as data. External function names are published 
via public declarations. 


literal data - such as strings and switch tables, are normally generated 
into the .text section. 


Anitialized data - are normally generated into the .data section. Exter- 
nal data names are published via public declarations. 


uninitialized declarations - result in a public reference, one instance 
per program file. 


function calls - are performed by 


1) moving arguments on the stack, right to left. Character data is 
sign-extended to integer, float is zero-padded to double. 


2) calling via "call func", 
3) popping the arguments off the stack. 


Except for returned value, the registers fa, bc, and hl, and the in- 
core pseudo registers ¢.r0 and c.ri, are undefined on return from a 
function call. All otner registers are preserved. The returned 
value is in bc (char sign-extended to integer, integer, pointer to), 
or in c.rO (long, float widened to double, double). c.rO and o.r! 
are each eight-byte memory areas that are not preserved on a function 
call; c.r2, c.r3, and c.rl are each two-byte memory areas that must 
be preserved on a function call. 


Stack frames - are maintained by each C function, using de as a frame 
pointer. On entry to a function, the call "call c.ents" will stack 
de and leave it pointing at the stacked de, then stack c.r2, c.r3, 
and c.r}. Arguments are at li(de), 6(de), etc. and auto storage may 
be reserved on the stack at -7(de) on down. To return, the jump "jmp 
c.rets" will use de to restore de, sp, c.r4, c.r3, and c.r2, then 
return. The previous sp is ignored, so the stack need not be 
balanced on exit, and none of the potential return registers are 
used. If it is not necessary to save or restore c.r2, c.r3, and 
C.ril, the call "call c.ent" and jump "jmp c.ret" may be used instead. 
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Interface -2- Interface 


data representation - integer is the same as short, two bytes stored less 
significant byte first. Long integers are stored as two short in- 
tegers, more significant short first. All signed integers are twos 
complement. Floating numbers are represented as for the PDP-11 
Floating Point Processor, four bytes for float, eight for double, and 
are stored as two or four short integers, in descending order of sig- 
nificance. 


storage bounds - no storage bounds need to be enforced.  Two-byte boun- 
daries may be enforced, inside structures and among automatic 
variables, to ensure data structure compatibility with machines such 
as the PDP-11, but boundaries stronger than this are not fully sup- 
ported by the stacking hardware; the compiler may generate incorrect. 
code for passing long or double arguments if a boundary stronger than 
even is requested. 


module name - is not produced. 


SEE ALSO 
c.ent(IV), c.ents(IV), c.entx(IV), c.rO(IV), c.ret(IV), c.rets(IV) 
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Conventions III.c. ISIS-II System Interface Library Conventions 


NAME 
Conventions - ISIS-II system subroutines 


SYNOPSIS 
#include <isis-h> 


FUNCTION 
All standard system library functions callable fron C follow a set of 
uniform conventions, many of which are supported at compile time by in- 
cluding a system header file, «isis.h», at the top of each program. Note 
that thís header is used in addition to the standard header <std.n>. The 
system header defines various system parameters and a useful macro or two. 


Herewith the principal definitions: 


FAIL - -1, standard failure return code 
IOPEN - 0, ISIS-II system call codes 
ICLOSE - 1 

IDELETE - 2 

IREAD - 3 

IWRITE - 4 

ISEEK - 5 

ILOAD - 6 

IRENAME - 7 

ICONSOL - 8 

IEXIT - 9 

IATTRIB + 10 

IRESCAN - 11 

IERROR - 12 

IWHOCON - 13 

ISPATH - 14 

NFILES - 9, maximum number of open files 
WOPEN - 1, WCB flags 

WCR - 2 


SEE ALSO 
ISIS-II Manual 
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main III.c. ISIS-II System Interface Library main 


NAME 

main - setup for main call 
SYNOPSIS 

BOOL main() 
FUNCTION 


main is the function called whenever a C program is started. It reads 
the remainder of the command line from STDIN, parses it into argument 
Strings, redirects STDIN and STDOUT as specified in the command line, then 
calls main. 


The command line is interpreted as a series of strings separated by 
spaces. If a string begins with a '«', tne remainder of the string is 
taken as the name of a file to be opened for reading text and used as the 
standard input, STDIN. If a string begins with a >’, the remainder of 
the string is taken as the name of a file to be oreated for writing text 
and used as the standard output, STDOUT. All other strings are taken as 
argument strings to be passed to main, which is called as desoribed in the 
Intro to the C SUBROUTINE MANUAL. The command name, av[0], is taken from 
.pname. 


EXAMPLE 
To avoid the loading of main and al) the the file I/0 code it calls on, 
one can provide a substitute main instead: 


BOOL main() 
H 
<program body» 
} 


tain returns the boolean value obtained from the main call, which is then 
passed to exit. 


SEE ALSO 
_Pname, exit 
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Jome II.c. ISIS-II System Interface Library _pome 
MAKE 


pname - program name 


FUNCTION 
_pname is the (NUL-terminated) name by which the program was invoked, at 
least as anticipated at compile time. If the user program provides no 
definition for _pname, a library routine supplies the name "error", since 
it is used primarily for labelling diagnostic printouts. 


Argument zero of the command line is set equal to _pname. 


SEE ALSO 
main 
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olose II.c. ISIS-II System Interface Library close 


NAME 
close - close a file 


SYNOPSIS 
FILE close(fd) 
FILE fd; 


FUNCTION 
close closes the file associated with the file descriptor fd, making the 
fd available for future open or oreate calls. 


RETURNS 
close returns the now useless file descriptor, if successful, or a nega- 
tive number, which is the ISIS-II error return code, negated. 


EXAMPLE 
To copy an arbitrary number of files: 


while (0 <= (fd = getfiles(&ac, &av, STDIN, -1))) 
t 
while (0 € (n = read(fd, buf, BUFSIZE))) 


write(STDOUT, buf, n); 
ciose(fd); 
) 


SEE ALSO 
Create, open, remove, uname 
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oreate III.c. ISIS-II System Interface Library create 


NAME 
create - open an empty instance of a file 


SYNOPSIS 
FILE create(name, mode, rsize) 
TEXT "nane; 
COUNT mode; 
BYTES rsize; 


FUNCTION 
create makes a new file of specified name, if it did not previously exist, 
or truncates the existing file to zero length. If (mode == 0) the file is 
opened for reading, else if (mode 1) it is opened for writing, else 


(mode == 2) of necessity and the file is opened for updating (reading and 
writing). 


If (rsize == 0), carriage returns are deleted on input, and a carriage 
return 1s injected before each newline on output. If (rsize l= 0) data is 
transmitted unaltered. 


RETURNS 


ereate returns a file descriptor for the created file or a negative num- 
ber, which is the ISIS-II error return code, negated. 


EIAMPLE 
if ((fd = create("xeq", WRITES, 1)) < 0) 
Write(STDERR, "can't create xeq\n", 17); 


SEE ALSO 
close, open, remove, uname 
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exit III.c. ISIS-II System Interface Library exit 


NAME 
exit - terminate program execution 


SYNOPSIS 
VOID exit(success) 
BOOL success; 


FUNCTION 
exit calls all functions registered with onexit, then terminates program 
execution. success is ignored. 


exit will never return to the caller. 


EXAMPLE 
if ((fd = open("file", READ)) < 0) 
t 


write(STDERR, "can't open file\n", 16); 
exit(NO); 
) 


SEE ALSO 
onexit 
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dais 


III.c. ISIS-II System Interface Library 


isis - call ISIS-II 


SYNOPSIS 
struct ob #isis(code, peb) 


COUNT code; 
struct cb #peb; 


isis is the C callable entry to the ISIS-II system. 


isis 


It loads the less 


significant byte of code into the c register, and pob into de, then calls 


ISIS-II. 
RETURNS 


isis returns pcb. 


EXAMPLE 


To close a file: 


IMPORT WCB wcb[]; 
COUNT stat; 
struct [ 
COUNT aftn, *pstat; 
} ob; 


cb.aftn = web[fd].waftn; 
eb.pstat = &stat; 
isis(ICLOSE, &cb); 

return (stat ? -stat : fd); 


Each struct cb is typically a function of code. 
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lseek III.c. ISIS-II System Interface Library lseek 


NAME 
lseek - set file read/write pointer 


SYNOPSIS 
COUNT iseek(fd, offset, sense) 
FILE fd; 
LONG offset; 
COUNT sense; 


FUNCTION 

lseek uses the long offset provided to modify the read/write pointer for 
the file fd, under control of sense. If (sense 0) the pointer is set 
to offset, which should be positive; if (sense == 1) the offset is al- 
gebraically added to the current pointer; otherwise (sense ss 2) of 
necessity and the offset is algebraically added to the length of the file 
in bytes to obtain the new pointer. ISIS-II uses only the low order 22 
bits of the offset; the rest are ignored. 


RETURNS 
lseek returns zero if successful, or a negative number, which is the ISIS- 
II error return code, negated. 


EXAMPLE 
To read a 512-byte block: 


BOOL getblock(buf, blkno) 
TEXT "buf; 
BYTES blkno; 
t 
lseek(STDIN, (LONG)blkno << 9, 0); 
return (read(STDIN, buf, 512) != 512); 
H 


BUGS 
It doesn't check for illegal values of sense, which can cause mayhem when 
used by ISIS-II. 
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onexit III.c. ISIS-II System Interface Library onexit 


NAME 
onexit - call function on program exit 


SINOPSIS 
VOID (*onexit())(pfn) 
VOID (*(5pfn)O00; 


FUNCTION 
onexit registers the funotion pointed at by pfn, to be called on program 
exit. The function at pfn is obliged to return the pointer returned by 
the onexit call, so that any previously registered functions can also be 
called. 


RETURNS 
onexit returns a pointer to another function; it is guaranteed not to be 
NULL. 


EXAMPLE 
IMPORT VOID (*(*nextguy) ()) O , (#thisguy())(); 


if (tnextguy) 
nextguy = onexit(&thisguy); 


SEE ALSO 
exit 


BUGS 
The type declarations defy description, and are still wrong. 
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onintr II.c. ISIS-II System Interface Library onintr 


NAME 
onintr - capture interrupts 


SYWOPSIS 
VOID onintr(pfn) 
VOID (*pfn)O; 


FUNCTION 
onintr is supposed to ensure that the function at pfn is called on the oc- 
currence of an interrupt generated from the keyboard of a controlling ter- 
minal. (Typing a delete DEL, or sometimes a otl-C ETX, performs this ser- 
vice on many systems.) 


onintr is currently a dummy, on this system, so pfn is never called. 


RETURNS 
Nothing. 
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open III.c. ISIS-II System Interface Library open 


NAME 
open - open an existing file 


SYNOPSIS 
FILE open(name, mode, rsize) 
TEXT "name; 
COUNT mode; 
BYTES rsize; 


FUNCTION 
open associates a file descriptor with an existing file, or with a new in- 
stance if the file is to be written and does not currently exist. If 
(mode == 0) the file is opened for reading, else if (mode == 1) it is 
opened for writing, else (mode == 2) of necessity and the file is opened 
for updating (reading and writing). 


If (rsize == zero), oarriage returns are deleted on input, and a carriage 
return is injected before each newline on output. If (rsize {= 0) data is 
transmitted unaltered. 


open returns a file descriptor for the file or a negative number, which is 
the ISIS-II error return code, negated. 


if ((fd = open("xeq", WRITES, 1)) « 0) 
write(STDERR, "can't open xeq\n", 15); 


SEE ALSO 
close, create, remove, uname 
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read III.c. ISIS-II System Interface Library read 


NAME 
read - read characters from a file 


SYNOPSIS 
COUNT read(fd, buf, size) 
FILE fd; 
TEXT *buf; 
BYTES size; 


FUNCTION 
read reads up to size characters from the file specified by fd into the 
buffer starting at buf. If the file was created or opened with (rsize == 
0), or if STDIN is not redirected from the console, carriage returns are 
discarded on input. 


RETURNS 
If an error occurs, read returns a negative number which is the ISIS-II 
error code, negated; if end of file is encountered, read returns zero; 
otherwise the value returned is between 1 and size, inclusive. 


EXAMPLE 
To copy a file: 


while (0 < (n = read(STDIN, buf, BUFSIZE))) 
write(STDOUT, buf, n); 


SEE ALSO 
write 
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remove IfI.c. ISIS-II System Interface Library remove 


NAME 
remove - remove a file 


SYNOPSIS 
FILE remove(fname) 
TEXT *fname; 


FUNCTION 
remove deletes the file fname from the ISIS-II diskette. 


remove returns zero, if successful, or a negative number, which is the 
ISIS-II error return code, negated. 


EXAMPLE 
if (remove("temp.c") < 0) 
write(STDERR, "can't remove temp file\n", 23); 
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sbreak III.c. ISIS-II System Interface Library sbreak 


NAME 
Sbreak - set system break 


SYNOPSIS 
TEXT *sbreak(size) 
BYTES size; 


FUNCTION 
Sbreak moves the system break, at the top of the data area, algebraically 
up by size bytes. 


RETURNS 
If successful, sbreak returns a pointer to the start of the added data 
area; otherwise the value returned is NULL. 


if (1(p = sbreak(nsyms * sizeof (symbol)))) 
{ 
write(STDERR, "not enough room!\n", 17); 
exit(NO); 
} 


BUGS 
The stack is assumed to lie above the data area, so sbreak will return a 
NULL if the new system break lies above the current stack pointer; this 
may not be desirable behavior on all memory layouts. 
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uname III.c. ISIS-II System Interface Library uname 


uname - create a unique file name 


SYNOPSIS 


TEXT *uname() 


FUNCTION 


uname returns a pointer to tne start of a NUL-terminated name which is 
likely not to conflict with normal user filenames. The name may be 
modified by a suffix of up to three letters, so that a family of process- 
unique files may be dealt with. The name may be used as the first argu- 
ment to a create, or subsequent open, call, so long as any such files 
created are removed before program termination. It is considered bad man- 
ners to leave scratch files lying about. 


RETURNS 


uname returns the same pointer on every call, which is currently the 
string "ctempc.". The pointer will never be NULL. 


EXAMPLE 


if ((fd = create(uname(), WRITE, 0)) < 0) 
write(STDERR, "can't create sort temp\n", 23); 


SEE ALSO 


close, create, open, remove 
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write III.c. ISIS-II System Interface Library write 


NAME 
write - write characters to a file 


SYNOPSIS 
COUNT write(fd, buf, size) 
FILE fd; 
TEXT "buf; 
COUNT size; 


FUNCTION 
write writes size characters starting at buf to the file specified by fd. 
If the file was created or opened with (rsize == 0), or if STDOUT or 


STDERR is not redirected from the console, each newline output is preceded 
by a carriage return. 


RETURNS 
If an error occurs, write returns a negative number which is the ISIS-II 
error code, negated; otherwise the value returned should be size. 


EXAMPLE 
To copy a file: 


while (0 < (n = read(STDIN, buf, size))) 
write(STDOUT, buf, n); 


SEE ALSO 
read 
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IV. Machine Support Library for 8080 


Conventions using the 8080 Machine Support Library 


c.btou 
c.count 
c.dadd 
c.demp 
e.depy 
c.ddiv 
c.dmul 
c.dneg 
e.dsub 
c.dtd 
c.dtf 
e.dti 
e.dtl 
eatr 
c.ent 
c.ents 
c.entx 
c.ftd 
oc.idiv 
c.ihl 
c.ilsh 
c.imod 
c.imul 
c.irsh 
c.itd 
c.ladd 
c-land 
e.lelt 
c.lomp 
c.lcom 
c.lepy 
c.ldiv 
c.llsh 
c.lmod 
C.lmul 
c.lneg 
e.lor 
e.iret 
c.lrsh 
c.lsub 
c.ltd 
o.lxor 
e.rO 
c.repk 
c.ret 
c.rets 


unpack bits to unsigned 

counter for profiler 

add double into double 

compare two doubles 

copy double to double 

divide double into double 
multiply double into double 
negate double 

subtract double from double 

move double to double 

convert double to float 

convert double to int 

convert double to long 

convert double to int on stack 
enter a C function 

save registers on entering a C function 
save registers and check stack on entering a C function 
convert float to double 

divide integer by integer 

jump on hl 

integer left shift 

remainder of integer divided by integer 
multiply integer by integer 
integer right shift 

convert integer to double 

add long to long 

and long into long 

compare long to long, set NC 
compare long to long, set Z 
complement long 

copy long to long 

divide long by long 

long left shift 

remainder of long divided by long 
multiply long by long 

negate long 

or long into long 

return from runtime function 

long right shift 

subtract long from long 

convert long to double 

exclusive or long into long 

the double accumulator and other pseudo registers 
repack a double number 

return from a C function 

return from a C function 
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perform C switch statement 

divide unsigned by unsigned 

unsigned divide long by long 

remainder of unsigned long divided by long 
unsigned long right shift 

convert unsigned long to double 
remainder of unsigned divided by unsigned 
unpack a double number 

unsigned right shift 

convert unsigned to double 

pack unsigned into bits 

return from runtime compare function 
input from port 

output to port 


Conventions IV. Machine Support Library for 8080 Conventions 


WAME 
Conventions - using the 8080 Machine Support Library 


FUNCTION 

The 8080 Machine Support Library is a collection of those routines needed 
by the C compiler to augment the code it produces. It also turns out to 
be pretty useful to anyone who must write machine-level code for the 8080. 
To use it, however, requires at least a basic knowledge of how C does 
business. All the information you need to make use of the facilities in 
this section has been provided earlier; it is summarized here to assist 
the A-Natural programmer. 


Funetions are described in terms of their A-Natural interface, sínce they 
operate outside the conventional C calling protocol. Unless explicitly 
Stated otherwise, every function does obey the normal C calling convention 
that registers af, be, and hl are not preserved across a call. 


The data types of C are: 


char - or one byte integer. Never passed between functions. A char may 
also be unsigned. 


Short - or two-byte integer, also known simply as int or integer. Stored 
less significant byte first, as the 8080 prefers. 


unsigned — is the same as int, except that the sign bit is just another 
magnitude bit. All memory addresses are treated as unsigned, to byte 
level. 


long - or long integer, is a four-byte integer. Stored as two integers, 
more significant integer first. Note that this means the order of 
bytes in memory is (2, 3, 0, 1), where 0 is the least significant 
byte. This particular representation is more useful than may at 
first be apparent. A long may also be unsigned. 


float - is a four-byte floating point number. Representation is the same 
as double, with the last four bytes discarded, i.e., the four least 
significant fraction bytes. Never passed between functions. 


double - is an eight-byte floating point number. It is stored as four in- 
tegers, most significant integer first, i.e., in the order (6, 7, 4, 
5, 2, 3, 0, 1). Representation is the same as for PDP-11 computers: 
most significant bit is one for negative numbers, else zero; next 
eight bits are the characteristic, biased such that the binary expo- 
nent of the number is the characteristic minus 0200; remaining bits 
are the fraction, starting with the 1/4 weighted bit. If the charac- 
teristic is zero, the entire number is taken as zero and should be 
all zeros to avoid confusing some routines that take shortcuts. 
Otherwise, there is an assumed 1/2 added to ali fractions to put them 
in the interval [0.5, 1.0). The value of the number is the fraction, 
times -1 if the sign bit is set, times two raised to the exponent. 


Names in C may contain letters, digits, and underscores ^ '. To avoid 


collisions with predefined A-Natural identifiers, the compiler prepends an 


wei 


Conventions -2- Conventions 


underscore to each symbol. Thus, the function name "func" becones 
" func" in A-Natural. 


It is also important to understand the rules for calling C functions, and 
for being called: 


A function is called by first pushing its arguments onto the stack in 
reverse order, so that the location of the first argument is not a funo- 
tion of how many arguments are actually passed. char values are widened 
to int, float to double. Then the function is called via: 


call func 


It is the responsibility of the calling function to pop the arguments off 
tne stack; it is acceptable for the called function to modify the argu- 
ments, since a fresh copy is expected on each call. 


A C function may return one of the data types listed above. If the return 
value is char, it is widened to int and placed in bc; int and unsigned 
also are returned in bc. long values are returned in the first four bytes 
of the static area labelled c.r0. float values are widened to double, 
which is returned in the eight bytes of the static area labelled c.r0. 


A called function may otherwise clobber af, be, hl, and the eight-byte 
area labelled c.r!; de is used by C as a stack frame pointer and must be 
carefully preserved, as must the state of the stack as described above. 
There are also three two-byte static areas labelled c.r2, c.r3, and ceri, 
which C frequently uses; these must be meticulously saved and restored. 


See the manual pages for c.ent, c.ents, ¢.r0, c.ret, and c.rets for some 
assistance in the use of this calling sequence. 


SEE ALSO 
Techniques(I), for coding tips 
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a.btou IV. Machine Support Library for 8080 c.btou 


HAME 
¢.btou - unpack bits to unsigned 


SYNOPSIS 
/ pointer to bits on stack 
/ offset/size on stack 
call c.btou 
/ unsigned on stack 


FUNCTION 
c.btou is the internal routine called by C to unpack the bitfield at bits 
into an unsigned on the stack. The field is specified by the two bytes 
offset/size, where the less significant byte offset is the number of 
Places the bitfield must be shifted right to align it as an integer, and 
the more significant byte size is the number of bits in the field. offset 
is assumed to be in the range [0, 16), while size is in the range (0,16]. 


RETURNS 
C.btou returns the bitfield unpacked into an unsigned integer, left on the 
Stack. All registers but af are preserved, and the arguments are popped 
Off the stack. 


SEE ALSO 
c.utob 
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c.count IV. Machine Support Library for 8080 c.count 


NAHE 
c.count - counter for profiler 


SYNOPSIS 


hl = &L 
call c.count 


FUNCTION 
€.count is the function called on entry to each C function when code is 
compiled using the profiling option. hl points at a data word, initially 
zero, which is used by c.count to record where counts for that entry point 
are being maintained; hence, there should be a unique data word reserved 
for each separate call on c.count. 


RETURNS 
Nothing. af, be, and hl are not preserved. 
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0. dadd IV. Machine Support Library for 8080 c.dadd 


MAME 
¢.dadd - add double into double 


SYNOPSIS 
/ pointer to left on stack 
x pointer to right on stack 
call c.dadd 
/ pointer to left still on stack 


FUNCTION 
c.dadd is the internal routine called by C to add the double at right into 
the double at left. It does so without destroying any volatile registers, 
$0 the call oan be used much like an ordinary machine instruction. 


If right is zero, left is unchanged (x«0); if left is zero, right is 
copied into it (04x). Otherwise the number with the smaller charac- 
teristic is shifted right until it aligns with the other and the addition 
is performed algebraically. The answer is rounded. 


RETURNS 
C.dadd replaces its left operand with the closest internal representation 
to the rounded sum of its operands. All registers but af are preserved, 
and the right argument is popped off the stack. 


SEE ALSO 
c.ddiv, c.dmul, c.dsub 


It doesn't check for characteristics differing by huge amounts, to save 
shifting. (-0 + 0) and (-0 + -0) return -0. 
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e.domp IV. Machine Support Library for 8080 c.domp 


HAME 
c.domp - compare two doubles 


SYNOPSIS 
/ pointer to left on stack 
/ pointer to right on stack 
call c.demp 
/ no pointers left on stack 


FUNCTION 
c.demp is the internal routine called by C to compare the double at left 
with the double at right. The comparison involves no floating arithmetic 
and so is comparatively fast. -0 compares equal with +0. 


RETURNS 
c.demp returns NZ set properly in f to reflect (left :: right); C is the 
same as N. All registers but a are preserved, and the arguments are 
popped off the stack. 


SEE ALSO 
c.dsub 


a.dopy IV. Machine Support Library for 8080 c.dopy 


NAME 
C.depy - copy double to double 


SINOPSIS 
/ pointer to left in be 
/ pointer to right hl 
call c.depy 


FUNCTION 
¢.depy moves the double at right to the double at left. 
Nothing. None of the volatile registers af, bc, or hl are preserved. 


SEE ALSO 
e.lopy 
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o.ddiv IV. Machine Support Library for 8080 c.ddiv 


NAME 
e.ddiv - divide double into double 


SYNOPSIS 
/ pointer to left on stack 
/ pointer to right on stack 
call e.ddiv 
/ pointer to left still on stack 


FUNCTION 
e.ddiv is the internal routine called by C to divide the double at right 
into the double at left. It does so without destroying any volatile 
registers, so the call can be used much like an ordinary machine instruc- 
tion. 


If right is zero, left is set to the largest representable floating num- 
ber, appropriately signed (x/0); if left is zero, it is unchanged (0/x). 
Otherwise the right fraction is divided into the left and the right expo- 
nent is subtracted from that of the left. The sign of the result is nega- 
tive if the left and right signs differ, else it is positive. The result 
is rounded. 


RETURNS 
c.ddiv replaces its left operand with the closest internal representation 
to the rounded quotient (left/right), or a huge number if right is zero. 
All registers but af are preserved, and the right argument is popped off 
the stack. 


SEE ALSO 
c.dadd, c.dmul, ¢.dsub 
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0.dmul IV. Machine Support Library for 8080 c.dmul 


NAME 
c.dmul - multiply double into double 


SYWOPSIS 
/ pointer to left on stack 
/ pointer to right on stack 
call c.dmul 
/ pointer to left still on stack 


FUNCTION 
¢.dmul is the internal routine called by C to multiply the double at right 
into the double at left. It does so without destroying any volatile 


registers, so the call can be used much like an ordinary machine instruc- 
tion. 


If either right or left is zero, the result is zero (0*x, x*0). Otherwise 
the right fraction is multiplied into the left and the right exponent is 
added to that of the left. The sign of the result is negative if the left 
and right signs differ, else it is positive. The result is rounded. 


REIURNS 
c.dmul replaces its left operand with the closest internal representation 
to the rounded product of its operands. All registers but af are 
preserved, and the right argument is popped off the stack. 


SEE ALSO 
e.dadd, c.ddiv, c.dsub 
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o.dneg I¥. Machine Support Library for 8080 c.dneg 


NAME 
c.dneg - negate double 


SYNOPSIS 
Fi pointer to left on stack 
call c.dneg 
/ pointer to left still on stack 


FUNCTION 
c.dneg negates the double at left in place. If the number is normalized, 
an unnormalized zero will never be produced. 


RETURNS 
The value returned is -left stored at left. All registers but af are 
preserved. 
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c.dsub IV. Machine Support Library for 8080 e.dsub 


NAME 
C.dsub - subtract double from double 


SYNOPSIS 
/ pointer to left on stack 
/ pointer to right on stack 
call c.dsub 
/ pointer to left still on stack 


FUNCTION 
c.dsub is the internal routine called by C to subtract the double at right 
from the double at left. It does so without destroying any volatile 
registers, so the call can be used much like an ordinary machine instruc~ 
tion. 


c.dsub copies its right operand, negates the copy, and calls c.dadd. 


RETURNS 
c.dsub replaces its left operand with the closest internal representation 
to the rounded difference (left - right). All registers but af are 
preserved, and the right argument is popped off tne stack. 


SEX ALSO 
c.dadd, c.demp, c.ddiv, c.dmul 


BUGS 
(-0 - 0) and (-0 - -0) return -0. 
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o.dtd IV. Machine Support Library for 8080 c.dtd 


NAME 
c.dtd - move double to double 


SYNOPSIS 
/ pointer to left on stack 
/ pointer to right on stack 
call c.dtd 
rd pointer to left still on stack 


FUNCTION 
¢.dtd is the internal routine called by C to move a double at right into a 
double at left. 


RETURNS 
c.dtd returns a copy of the double at right in the double at left. All 
registers but af are preserved, and the right argument is popped off the 
stack. 


SEE ALSO 
C.dtf, c.ftd 
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o.dtf IV. Machine Support Library for 8080 o.dtf 


NAME 
c.dtf - convert double to float 


SYNOPSIS 
t pointer to left on stack 
/ pointer to right on stack 
call c.dtf 
/ pointer to left still on stack 


FUNCTION 
c.dtf is the internal routine called by C to convert the double at right 
into a float at left. It does so by rounding the fraction up if the first 
discarded bit is a one, adjusting the characteristic as necessary. 


RETURNS 
c.dtf returns a float in the location pointed at by left. All registers 
but af are preserved, and the right argument is popped off the stack. 


SEE ALSO 
e.dtd, c.ftd 
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adti IY. Machine Support Library for 8080 c.dti 


NAME 
¢.dti - convert double to int 


SYNOPSIS 
/ pointer to left on stack 
/ pointer to right on stack 
call c.dti 
/ pointer to left still on stack 


FUNCTION 
O.dti is the internal routine called by C to convert a double at right 
into an integer at left. It does so by calling c.unpk, to separate the 
fraction from the characteristic, then shifting the fraction until the 
binary point is at a known fixed place. The integer immediately to the 
left of the binary point is delivered, with the same sign as the original 
double. Truncation occurs toward zero. 


RETURNS 
c.dti returns a integer at left which is the low-order 16 bits of the in- 
teger representation of the double at right, truncated toward zero. All 
registers but af are preserved, and the right operand is popped off the 
stack. 


SEE ALSO 
c.dtr, c.itd 
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o.dti IV. Machine Support Library for 8080 c.dti 


MAME 
c.dtl - convert double to long 


SINOPSIS 
/ pointer to left on stack 
/ pointer to right on stack 
call c.dtl 
/ pointer to left still on stack 


FUNCTION 
¢.dtl is the internal routine called by C to convert a double at right 
into a long integer at left. It does so by calling c.unpk, to separate 
the fraction from the characteristic, then shifting the fraction until the 
binary point is at a known fixed place. The long integer immediately to 
the left of the binary point is delivered, with the same sign as the 
original double. Truncation occurs toward zero. 


RETURNS 
C.dti returns a long at left which is the low-order 32 bits of the integer 
representation of the double pointed at by right, truncated toward zero. 


All registers but af are preserved, and the right argument ia popped off 
the stack. 


SEE ALSO 
c.ltd 
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e.dtr IV. Machine Support Library for 8080 c.dtr 


NAME 
c.dtr - convert double to int on stack 
SYNOPSIS 
/ pointer to right on stack 
call c.dtr 


/ integer on stack 


FUNCTION 
c.dtr is the internal routine called by C to convert a double at right 
into an integer on the stack. It does so by calling c.unpk, to separate 
the fraction from the characteristic, then shifting the fraction until the 
binary point is at a known fixed place. The integer immediately to the 
left of the binary point is delivered, with the same sign as the original 
double. Truncation occurs toward zero. 


RETURNS 
¢.dtr returns a integer at left which is the low-order 16 bits of the in- 
teger representation of the double at right, truncated toward zero. All 
registers but af are preserved, and the right operand is popped off the 
stack. 


SEE ALSO 
c.dti, c.itd 
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oant IV. Machine Support Library for 8080 c.ent 


NAME 
c.ent - enter a C function 


SYNOPSIS 
call c.ent 


FUNCTION 
c.ent sets up a new stack frame. It is designed to be called on entry to 
a C function, at which time: 


2(sp) holds the first argument 
O(sp) holds the return link 


On return fom c.ent de matches sp and: 


4(de) holds first argument 
2(de) holds return link 
O(de) holds old de 


Automatic storage can be allocated by decrementing the stack pointer; it 
is addressed at -7(de) on down. 


RETURNS 
c.ent alters sp and de to make the new stack frame. af, bc, and hl are 
not preserved. 


EXAMPLE 
The C function: 


COUNT idiot() 
t 
COUNT i; 


return (1); 


3 


can be written: 


idiot: 
call c.ent 
sp «s af <z af <= af <= af / space for i 
bo z^ (hl = -8 + de) / return value 
jmp c.ret 
SEE ALSO 


c.ents, Ceret, c.rets 
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coentas IV. Machine Support Library for 8080 c.ents 


NAME 
c.ents - save registers on entering a C function 


SYNOPSIS 
call c.ents 


FUNCTION 
c.ents sets up a new stack frame and stacks c.r4, c.r3, and c.r2. It is 
designed to be called on entry to a C function, at which time: 


2(sp) holds tne first argument 
O(sp) holds the return link 


On return fom c.ents de holds sp«6 and: 


A(de) holds first argument 
2(de) holds return link 
O{de) holds old de 

-2(de) holds old c.rh 
-4(de) holds old c.r3 
-6(de) holds old c.r2 


Automatic storage can be allocated by decrementing the stack pointer; it 
is addressed at -7(de) on down. 


RETURNS 
c.ents alters sp and de to make the new stack frame. af, be, and hl are 
not preserved. 


EXAMPLE 
The C function: 


COUNT idiot() 
{ 
FAST COUNT i; 


return (i); 


ean be written: 


idiot: 
call c.ents 
be s^ (hl = c.r4)  / return value 
jup c.rets 


SEE ALSO 
c.ent, c.r0, o.ret, c.rets 
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o.entx IV. Machine Support Library for 8080 c.entr 


MAME 
c.entx - save registers and check stack on entering a C function 


SYNOPSIS 
hl - &nautos 
eall c.entx 


FUNCTION 
c.entx sets up a new stack frame, stacks c.r}, c.r3, and c.r2, and ensures 
that nautos+sp is not lower than stop, to check for stack overflow. It 
is designed to be called on entry to a C function, at which time: 


2(sp) holds the first argument 
O(sp) holds the return link 


On return fom c.entx de holds sp+6 and: 


4(de) holds first argument 
2(de) holds return link 
O(de) holds old de 

-2(de) holds old c.rli 
-l(de) holds old c.r3 
-6(de) holds old c.r? 


Automatio storage can be allocated by deorementing the stack pointer; it 
is addressed at -7(de) on down. 


If stack overflow would occur, the memerr condition is raised. This will 
never happen if stop is set to zero. 


RETURNS 
c.entx alters sp and de to make the new stack frame. af, bo, and hl are 
not preserved. 


EXAMPLE 
The C function: 


COUNT idiot() 
{ 
FAST COUNT i; 


return (i); 


can be written: 


idiot: 
hl = &-24 
call c.entx 
be s^ (hl = c.r) / return value 
jmp c.rets 


SEE ALSO 
c.ent, c.ents, c.r0, cret, c.rets 
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o.ftd IV. Machine Support Library for 8080 e.ftd 


NAME 
¢.ftd - convert float to double 


SYNOPSIS 
/ pointer to left on stack 
/ pointer to right on stack 
call c.ftd 
/ pointer to left still on stack 


FUNCTION 
c.ftd is the internal routine called by C to convert the float at right 
into a double at left. It does so by appending four fraction bytes of 
zeros to the four-byte float. 


RETURNS 
c.ftd returns a double in the location pointed at by left whose value 
matches the float at right. All registers but af are preserved, and the 
right argument is popped off the stack. 


SEE ALSO 
c.dtd, c.dtf 
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o.idiv IV. Machine Support Library for 8080 e.idiv 


MAME 
c.idiv - divide integer by integer 


SYNOPSIS 
/ left on stack 
/ right on stack 
call c.idiv 
/ quotient on stack 


FUNCTION 
c.idiv divides the integer left by the integer right to obtain the integer 
quotient. The sign of a nonzero result is negative only if the signs of 
left and right differ. No check is made for division by zero, which cur- 
rently gives a quotient of -1 or «1. 


RETURNS 
The value returned is the integer quotient of left/right on the stack. 


All registers but af are preserved, and the arguments are popped off the 
stack. 


SEE ALSO 
c.imod, c.udiv, c.umod 


IV - 21 


o. ihl IV. Machine Support Library for 8080 c.ihl 


NAME 
c.ihl - jump on hl 
SYNOPSIS 
hl = &funo 
cali c.ihl 
FUNCTION 


C.ihl is used by the C compiler to enter a function whose address is not 
known at compile time, as when calling a function given a pointer to it. 
It simply performs a 

jmp *hl 
which presumably enters the function. 


c.ihl can also be used as the target of various conditional jumps and 
calls, to extend the reach of these instructions. 


RETURNS 
C.ihl returns whatever the function at hl returns. 
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oilsh IV. Machine Support Library for 8080 c.ilsh 


NAME 
e.ilsh - integer left shift 


SYNOPSIS 
/ integer val on stack 
/ integer count on stack 
call c.ílsh 
/ integer result on stack 


FUNCTION 
c.ilsh shifts the integer val left by the integer count. If count is 
negative, an arithmetic right shift occurs instead. If count is positive, 
the result is valid for unsigned val. 


RETURNS 
The value returned is the shifted integer result val<<count on the stack, 
All registers but af are preserved, and the arguments are popped off the 
stack. 


SEE ALSO 
ec.irsh, c.ursh 


BUGS 
count is blindly reduced modulo 256; no checking is performed for 
ridiculously long shifts (16, 128), which take a long time. 
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c.imod IV. Machine Support Library for 8080 c.imod 


NAME 
c.imod ~ remainder of integer divided by integer 


SYNOPSIS 
/ left on stack 
/ right on stack 
call c.imod 
/ remainder on stack 


FUNCTION 
c.imod divides the integer left by the integer right to obtain the integer 
remainder. The sign of a nonzero resuit is the same as the sign of left. 
No check is made for division by zero, which currently gives a remainder 
equal to left. 


RETURNS 
The value returned is the integer remainder leftfright on the stack. All 
registers but af are preserved, and the arguments are popped off the 
stack. 


SEE ALSO 
c.idiv, c.udiv, c.umod 
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0. imul IV. Machine Support Library for 8080 c.imul 


NAME 
c.imul - multiply integer by integer 


SYNOPSIS 
/ integer left on stack 
/ integer right on stack 
call c.imul 
/ integer result on stack 


FUNCTION 
c.imul multiplies the integer left by the integer right to obtain the in- 
teger product. The sign of a nonzero result is negative only if the signs 
of left and right differ. No check is made for overflow, which currently 
gives the low order 16 bits of the correct product. The result of o.imul 
is also valid for unsigned operands. 


RETURNS 
The value returned is the integer product left*right on the stack. All 
registers but af are preserved, and the arugments are popped off the 
stack. 


SEE ALSO 
c.idiv, c.imod, c.udiv, c.umod 
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6.irsh IV. Machine Support Library for 8080 o.irsh 


NAME 
c.irsh - integer right shift 


STNOPSIS 
/ integer val on stack 
/ integer count on stack 
call c.irsh 
/ integer result on stack 


FUNCTION 
c.irsh shifts the integer val right by the integer count. If count is 
negative, a left shift occurs instead. 


RETURNS 
The value returned is the shifted integer result val>>count on the stack. 
All registers but af are preserved, and the arguments are popped off the 
stack. 


SEE ALSO 
c.ilsh, c.ursh 


BUGS 
count is blindly reduced modulo 256; no checking is performed for 
ridiculously long shifts (16, 128), which take a long time. 
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o.itd IV. Machine Support Library for 8080 o.itd 


c.itd - convert integer to double 


SYNOPSIS 
/ pointer to left on stack 
/ right on stack 
call c.itd 
/ pointer to left still on stack 


PUNCTION 
C.itd is the internal routine called by C to convert the integer right 
into a double at left. It does so by extending the integer to an unpaoked 
double fraction, then calling c.repk with a suitable characteristic. It 
does so without destroying any volatile registers, so the call can be used 
much as an ordinary machine instruction. 


RETURNS 
C.itd replaces the operand at left with the double representation of the 
integer right. All registers but af are preserved, and the right argument 
is popped off the stack. 


SEE ALSO 
€.dti, c.utd, c.repk 
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e@.ladd IV. Machine Support Library for 8080 c.ladd 


NAME 
Cc.ladd - add long to long 


SYNOPSIS 
4 pointer to left on stack 
/ pointer to right on stack 
call c.ladd 
/ pointer to left still on stack 


FUNCTION 
c.ladd adds the long at right to the long at left to obtain the long sum. 
No check is made for overflow, which currently gives the low order 32 bits 
of the correct sum. The result of c.ladd is also valid for unsigned 
operands. 


RETURNS 
The value returned is the long sum lefteright stored at left. All 
registers but af are preserved, and the right argument is popped off the 
stack. 


SEE ALSO 
c.lsub 


IV - 28 


o.land I¥. Machine Support Library for 8080 c.land 


NAME 
c.land - and long into long 


SYNOPSIS 
/ pointer to left on stack 
/ pointer to right on stack 
call c.land 
/ pointer to left still on stack 


FUNCTION 
¢.land ands the long at right into tne long at left to obtain the long 
logical intersection. 


RETURNS 
The value returned is the long intersection left&right stored at left. 
All registers but af are preserved, and the right argument is popped off 
tne stack. 


SEE ALSO 
celor, c.lxor 
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9.1olt IV. Machine Support Library for 8080 e.lelt 


NAME 
c.lclt - compare long to long, set NC 


SYNOPSIS 

/ pointer to left on stack 

/ pointer to right on stack 
call c.lelt 

/ no pointers left on stack 


FUNCTION 
c.lclt compares the long at right to the long at left to set the N and C 
flags in f. No check is made for overflow, which currently gives er- 
roneous settings for N if the arguments differ widely. The setting of C 
is always correct for unsigned operands, however. 


RETURNS 
C.lclt returns NC set properly in f to reflect (left :: right); Z is not 
set properly. All registers but a are preserved, and the arguments are 
popped off the stack. 


SEE ALSO 
¢.lemp 
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o.lomp IV. Machine Support Library for 8080 c.lomp 


WAME 
c.lemp - compare long to long, set Z 


SYNOPSIS 
/ pointer to left on stack 
z pointer to right on stack 
call c.lemp 
/ no pointers left on stack 


FUNCTION 
c.lemp compares the long at right to the long at left to set the Z flag in 
f. 


RETURNS 
c.lemp returns Z set properly in f to reflect (left :: right); N and C 


are not set properly. All registers but a are preserved, and the argu- 
ments are popped off the stack. 


SEE ALSO 
o.lelt 
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6.lcom IV. Machine Support Library for 8080 c.lcom 


NAHE 
c.loom - complement long 


SYNOPSIS 
/ pointer to left on stack 
call c.lcom 
/ pointer to left still on stack 


FUNCTION 
€.lcom complements the long at left in place. 


RETURNS 
The value returned is “left, stored at left. 


preserved. 


SEE ALSO 
c.lneg 
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All registers but af are 


o.lopy IV. Machine Support Library for 8080 o.lepy 


NAME 
cG.lepy - copy long to long 


SYNOPSIS 
/ pointer to left in bc 
/ pointer to right hi 
call c.lcpy 


PUNCTION 
c.lepy moves the long at right to the long at left. 


RETURNS 
Nothing. None of the volatile registers af, bc, or hl are preserved. 


SEE ALSO 
c.depy 
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e-1div IV. Machine Support Library for 8080 c.ldiv 


NAME 
c.ldiv - divide long by long 


SYNOPSIS 
/ pointer to left on stack 
/ pointer to ríght on stack 
call c.ldiv 
/ pointer to left still on stack 


FUNCTION 
c.ldiv divides the long at left by the long at right to obtain the long 
quotient. The sign of a nonzero result is negative only if the signs of 
left and right differ. No check is made for division by zero, which cur- 
rently gives a quotient of -1 or +1. 


RETURNS 
The value returned is the long quotient of left/right stored at left. All 
registers but af are preserved, and the right argument is popped off the 
stack. 


SEE ALSO 
@.lmod, c.uldiv, c.ulaod 
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o.llsh I¥. Machine Support Library for 8080 c.llsh 


NAME 
e.llsh - long left shift 


SYNOPSIS 
/ pointer to val on stack 
/ integer count on stack 
call c.llsh 
/ pointer to val still on stack 


FUNCTION 
¢.llsh shifts the long at val left by the integer count. If count is 
negative, an arithmetic right shift occurs instead. If count is positive, 
the result is valid for unsigned long val. 


RETURES 
The value returned is the shifted long result val<<count stored at val. 
All registers but af are preserved, and the count argument is popped off 
the stack. 


SEE ALSO 
C.lrsh, c.ulrsh 


BUGS 


count is blindly reduced modulo 256; no checking is performed for 
ridiculously long shifts (32, 128), which take a long time. 
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6.1mod IV. Machine Support Library for 8080 c.1mod 


NAME 
c.lmod ~ remainder of long divided by long 


SYNOPSIS 
/ pointer to left on stack 
/ pointer to right on stack 
call c.lmod 
/ pointer to left still on stack 


FUNCTION 
c.imod divides the long at left by the long at right to obtain the long 
remainder. The sign of a nonzero result is the same as the sign of left. 
No check is made for division by zero, which currently gives a remainder 
equal to left. 


RETURNS 
The value returned is the long remainder leftáright stored at left. All 
registers but af are preserved, and the right argument is popped off the 
stack. 


SEE ALSO 
c.ldiv, c.uldiv, c.ulmod 
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o. imul IV. Machine Support Library for 8080 c.1mul 


NAME 
c.lmul - multiply long by long 


SYNOPSIS 
/ pointer to left on stack 
/ pointer to right on stack 
call c.1mul 
/ pointer to left still on stack 


FUNCTION 
c.lmul multiplies the long at left by the long at right to obtain the long 
product. The sign of a nonzero result is negative only if the signs of 
left and right differ. No check is made for overflow, which currently 
gives the low order 32 bits of the correot product. The result of c.lmul 
is also valid for unsigned operands. 


RETURNS 
The value returned is the long product left'right stored at left. All 
registers but af are preserved, and the right argument is popped off the 
stack. 


SEE ALSO 
c.ldiv, c.lmod, c.uldiv, c.ulmod 


Iv - 37 


G.lneg IV. Machine Support Library for 8080 c.lneg 


NAME 
c.lneg - negate long 


SYNOPSIS 
/ pointer to left on stack 
call e.lneg 
/ pointer to left still on stack 
FUNCTION 
c.lneg negates the long at left in place. No check is made for overflow. 
RETURNS 
The value returned ís -left stored at left. All registers but af are 
preserved. 
SEE ALSO 
Celcom 
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@.lor IV. Machine Support Library for 8080 clor 


MAME 
C.lor - or long into long 


SYNOPSIS 
/ pointer to left on stack 
/ pointer to right on stack 
call c.lor 
/ pointer to left still on stack 


FUNCTION 
O.lor ors the long at right into the long at left to obtain the long 
logical union. 


RETURNS 
The value returned is the long union left/right stored at left. All 
registers but af are preserved, and the right argument is popped off the 
Stack, 


SEE ALSO 
c.land, c.lxor 
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0.1ret IV. Machine Support Library for 8080 o.lret 


NAME 
c.lret - return from runtime function 
SYNOPSIS 
/ stack: be, hl, pe, right, and left 
jmp c.lret 
FUNCTION 


C.lret is the code sequence used to return from several of the runtime 
functions. It assumes that the stack is setup as follows: 


B(sp) left operand 
6(sp) right operand 
4(sp) return link 
2(sp) old hl 

O(sp) old tc 


It is assumed that the left operand has been overwritten with the result 
of the function, which is to be left on the stack. 


RETURNS 
c.lret returns with the old bc and hl restored and just the result left on 
the stack. de is preserved, but af is undefined. 


SEE ALSO 
c.zret 
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0.1rsh IV. Machine Support Library for 8080 c-1rsh 


NAME 
c.lrsh - long right shift 


SYNOPSIS 
/ pointer to val on stack 
/ integer count on stack 
call c.lrsh 
/ pointer to val still on stack 


FUNCTION 
c.lrsh shifts the long at val right by the integer count. If count is 
negative, a left shift occurs instead. 


RETURNS 
The value returned is the shifted long result val>>count stored at val. 


All registers but af are preserved, and the count argument is popped off 
the stack. 


SEE ALSO 
c.llsh, ¢.ulrsh 


BUGS 


count is blindly reduced modulo 256; no checking is performed for 
ridiculously long shifts (32, 128), which take a long time. 


Ww-41 


o.lsub IV. Machine Support Library for 8080 ¢.lsub 


NAME 
e.lsub - subtract long from long 


SYNOPSIS 
/ pointer to left on stack 
/ pointer to right on stack 
call c.lsub 
/ pointer to left still on stack 


FUNCTION 
O.lsub subtracts the long at right from the long at left to obtain the 
long difference. No check is made for overflow, which currently gives the 
low order 32 bits of the correct sum. The result of o.lsub is also valid 
for unsigned operands. 


RETURNS 
The value returned is the long difference left-right stored at left. All 
registers but af are preserved, and the right argument is popped off the 
Stack. 


SEE ALSO 
c.ladd 
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G.1td IV. Machine Support Library for 8080 c.1td 


HAME 
c.ltd - convert long to double 


SYNOPSIS 
A pointer to left on stack 
/ pointer to right on stack 
call c.ltd 
/ pointer to left still on stack 


FUNCTION 
c.ltd is the internal routine called by C to convert the long at right 
into a double at left. It does so by extending the long to an unpacked 
double fraction, then calling c.repk with a suítable characteristic. It 
does so without destroying any volatile registers, so the call can be used 
much like an ordinary machine instruction. 


RETURKS 
¢-ltd replaces the operand at left with the double representation of the 
long at right. All registers but af are preserved, and the right argument 
is popped off the stack. 


SEE ALSO 
e.dtl, c.repk, c.ultd 
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o.lxor IV. Machine Support Library for 8080 c.lxor 


NAME 
c.1xor - exclusive or long into long 


SYNOPSIS 
T pointer to left on stack 
A pointer to right on stack 
call c.lxor 
4 pointer to left still on stack 


FUNCTION 
c.lxor exclusive ors the long at right into the long at left to obtain the 
long logical symmetric difference. 


RETURNS 
The value returned is the long symmetric difference left^right stored at 
left. All registers but af are preserved, and the right argument is 
popped off the stack. 


SEE ALSO 
c.land, c.lor 
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oro IV. Machine Support Library for 8080 cro 


c.rO - the double accumulator and other pseudo registers 


co 


coooco 


FUNCTION 


c.r0 is an eight-byte static area used for returning long and double 
results from C functions. It is accompanied by o.r!, another eight-byte 
area, and three two-byte registers c.r2, c.r3, and c.nli. c.r0 and o.r1 
are considered volatile, and hence may be used freely by any function; 
c.r2, c.r3, and c.rl must be preserved. The function entry and exit 
utilities c.ents and c.rets are used to save and restore the nonvolatile 
pseudo registers. 


Since the 8080 is short on registers, and since it is better at directly 
addressing memory than addressing relative to a base register, the use of 
the pseudo registers can significantly reduce the size of a function. Tne 
C compiler allocates up to three non-volatile registers to honor register 
declarations, and uses c.r0 and c.r! as long or double arithmetic ac- 
cumulators. 


e.r0 doesn't return anything; it just stands there. Doubles fill all 
eight-bytes, in the usual format; longs are packed into the first four 
bytes, also in the usual format for longs in memory. 


SEE ALSO 


cents, crets 
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o.repk IV. Machine Support Library for 8080 c.repk 


NAME 
c.repk - repack a double number 


SYNOPSIS 
/ characteristic on stack 
/ pointer to frac on stack 
call c.repk 
sp => af => af 


FUNCTION 

c.repk is the internal routine called by various floating runtime routines 
to pack a signed fraction at frac and a two-byte binary characteristic 
into a standard form double representation. The fraction occupies nine 
bytes, starting at frac and stored least significant byte first, and may 
contain any value; there is an assumed binary point immediately to the 
right of the most significant byte. The characteristic is 0200 plus the 
power of two by which the fraction must be multiplied to give the proper 
value. 


If the fraction is zero, the resulting double is all zeros. Otherwise the 
fraction is forced positive and shifted left or right as needed to bring 
the fraction into the interval [0.5, 1.0), with the characteristic being 
incremented or decremented as appropriate. The fraction is then rounded 
to 56 binary places. If the resultant characteristic can be properly 
represented in a double, it is put in place and the sign is set to match 
the original fraction sign. If the characteristic is zero or negative, 
the double is all zeros. Otherwise the characteristic is too large, 30 
the double is set to the largest representable number, and is given the 
sign of the original fraction. 


RETURNS 
c.repk replaces the first eight (least significant) bytes of the fraction 
With the double representation, i.e., four two-byte integers, most síg- 
nificant integer first. The value of tne function is VOID, i.e., garbage. 
The registers af, bo, and hl are not preserved. 


SEE ALSO 
c.unpk 


BUGS 
Really large magnitude values of char might overflow during normalization 
and give the wrong approximation to an out of range double value. 
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e.ret IV. Machine Support Library for 8080 c.ret 


NAME 
c.ret - return from a C function 
SYNOPSIS 
jmp cret 
FUNCTION 


C.ret restores the stack frame in effect on a C call and returns to the 
routine that called the C function. It is assumed that the new frame was 
set up by a call to c.ent. The stack frame pointer de is used to roll 
back the stack, so sp need not be in a known state (i.e., junk may be left 
on the stack). 


RETURNS 
¢.ret restores de and leaves bo unchanged, so as not to disturb a returned 
value. af and hl are not preserved. 


EXAMPLE 
The C function: 


COUNT idiot() 
t 
COUNT i; 


eurn U); 


can be written: 


idiot: 
call c.ent 
sp <= af <= af <= af <zaf / space for i 
be z^ (hl = -8 + de) / return value 
jmp c.ret 
SEE ALSO 


c.ent, c.ents, c.rets 
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e.rets 1V. Machine Support Library for 8080 c.rets 


NAME 
e.rets - return from a C function 
SYNOPSIS 
jmp c.rets 
FUNCTION 


c.rets restores the stack frame and registers in effect on a C call and 
returns to the routine that called the C function. It is assumed that the 
new frame was set up by a call to c.ents. The stack frame pointer de is 
used to locate the stored c.r2, c.r3, c.r4, and de and to roll back the 
Stack, so sp need not be in a known state (i.e., junk may be left on the 
stack). 


RETURNS 
c.rets restores all non-volatile registers and leaves unchanged be, c.r0, 
and c.ri, so as not to disturb a returned value. af and hl are not 
preserved. 
The C function: 
COUNT idiot() 
i 
FAST COUNT 1; 


return (1); 


can be written: 


idiot: 
call c.ents 
be = (hl s c.r0) / return value 


jmp c.rets 


SEE ALSO 
c.ent, c.ents, c.rO, c.ret 
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0.Switch 1V. Machine Support Library for 8080 c.suiteh 


NAME 
€.switch - perform C switch statement 
SYWOPSIS 
bc - val 
= &swtab 
jmp c.switch 
FUNCTION 


c.switch is the code that branches to the appropriate case in a switch 
statement. It compares val against each entry in swtab until it finds an 
entry with a matching case value or until it encounters a default entry. 
swtab entries consist of zero or more (1bl, value) pairs, where 1bl is the 
(nonzero) address to jump to and value is the integer case value that must 
matoh val. 


A default entry is signalled by the pair (0, deflbl), where deflbl is the 
address to jump to if none of the case values match. The compiler always 
provides a default entry, which is the statement following the switch if 
there is no explicit default statement within tne switch. 


c.SWitch exits to the appropriate case or default; it never returns. The 
registers af, bo, and hl are not preserved. 
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e.udiv IV. Machine Support Library for 8080 c.udiv 


c.udiv - divide unsigned by unsigned 


SYNOPSIS 
/ left on stack 
y right on stack 
call c.udiv 
/ quotient on stack 


FUNCTION 
C.udiv divides the unsigned left by the unsigned right to obtain the un- 
Signed quotient. No check is made for division by zero, which currently 
gives a quotient of all ones. 


RETURNS 
The value returned is the unsigned quotient of left/right on the stack, 
All registers but af are preserved, and the arguments are popped off the 
stack. 


SEB ALSO 
c.imod, c.idiv, c.umod 
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6.uldiv IV. Machine Support Library for 8080 c.uldiv 


NAME 
C.uldiv - unsigned divide long by long 


SYNOPSIS 
/ pointer to left on stack 
/ pointer to right on stack 
call c.uldiv 
/ pointer to left still on stack 


FUNCTION 
e.uldiv divides the unsigned long at left by the unsigned long at right to 
obtain the unsigned long quotient. No check is made for division by zero, 
which currently gives a quotient of all ones. 


RETURNS 
The value returned is the unsigned long quotient of left/right stored at 
left. All registers but af are preserved, and the right argument is 
popped off the stack. 


SEE ALSO 
C.lmod, c.ldiv, c.ulmod 
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0. ulmod IV. Machine Support Library for 8080 c.ulmod 


NAME 
c.ulmod - remainder of unsigned long divided by long 


SYNOPSIS 
/ pointer to left on stack 
/ pointer to right on stack 
call c.ulmod 
/ pointer to left still on stack 


FUNCTION 
c.ulmod divides the unsigned long at left by the unsigned long at right to 
obtain the unsigned long remainder. No check is made for division by 
zero, which currently gives a remainder equal to left. 


RETURNS 
The value returned is the unsigned long remainder left%right stored at 
left. All registers but af are preserved, and the right argument is 
popped off the stack. 


SEE ALSO 
c.ldiv, o.lmod, c.uldiv 


Iv - 52 


0.ulrsh IS. Machine Support Library for 8080 c.ulrah 


NAME 
c.ulrsh - unsigned long right shift 


SYNOPSIS 
/ pointer to val on stack 
/ integer count on stack 
call c.ulrsh 
/ pointer to val still on stack 


FUNCTION 
c.ulrsh shifts the unsigned long at val right by the integer count. If 
count is negative, a left shift occurs instead. 


RETURNS 
The value returned is the shifted unsigned long result val>>count stored 
at val. All registers but af are preserved, and the count argument is 
popped off the stack. 


SEE ALSO 
¢.llsh, c.lrsh 


BUGS 


count is blindly reduced modulo 256; no checking is performed for 
ridiculously long shifts (32, 128), which take a long time. 
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0.ultd IV. Machine Support Library for 8080 c.ultd 


NAME 
c.ultd - convert unsigned long to double 


SYNOPSIS 
/ pointer to left on stack 
/ pointer to right on stack 
call c.ultd 
/ pointer to left still on stack 


FUNCTION 
C.ultd is the internal routine called by C to convert the unsigned long at 
right into a double at left. It does so by extending the unsigned long to 
an unpacked double fraction, then calling c.repk with a suitable charac- 
teristic. It does so without destroying any volatile registers, so the 
call can be used much like an ordinary machine instruction. 


RETURNS 
c.ultd replaces the operand at left with the double representation of the 
unsigned long at right. All registers but af are preserved, and the right 
argument is popped off the stack. 


SEE ALSO 
c.dtl, c.ltd, c.repk 
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c.umod IV. Machine Support Library for 8080 c.umod 


NAME 
c.umod - remainder of unsigned divided by unsigned 


SYNOPSIS 
/ left on stack 
/ right on stack 
call c.umod 
/ remainder on stack 


FUNCTION 
c.umod divides the unsigned left by the unsigned right to obtain the un- 
Signed remainder. No check is made for division by zero, which currently 
gives a remainder equal to left. 


RETURNS 
The value returned is the unsigned remainder left%right on the stack. All 
registers but af are preserved, and the arguments are popped off the 
stack. 


SRE ALSO 
c.idiv, c.imod, c.udiv 


IV - 55 


6.unpk IV. Machine Support Library for 8080 c.unpk 


NAME 
c.unpk - unpack a double number 


SYNOPSIS 
/ pointer to double on stack 
/ pointer to frac on stack 
call c.unpk 
sp => af => af 


FONCTION 

c.unpk is the internal routine called by various floating runtime routines 
to unpack a double at double into a signed fraction at frac and a charac- 
teristic. The fraction consists of nine bytes at frac, stored least sig- 
nificant byte first; the binary point is immediately to the right of the 
most significant byte. If the double at double is not zero, c.unpk 
guarantees that the magnitude of the fraction is in the interval [0.5, 
1.0). The least significant byte is guaranteed to be zero; it serves as 
a guard byte. 


The characteristic returned is 0200 plus the power of two by which the 
fraction must be multiplied to give the proper value; it will be zero for 
any flavor of zero at double (i.e., having a characteristic of zero, ir- 
respective of other bits). 


RETURNS 
c.unpk writes the signed fraction as nine bytes starting at frac and 
stored least significant byte first, and returns the characteristic in be 
as the value of the function. The registers af and hl are not preserved. 


SEE ALSO 
c.repk 
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o.ursh IV. Machine Support Library for 8080 c.ursh 


NAME 
c.ursh - unsigned right shift 


SYNOPSIS 
$ unsigned val on stack 
/ integer count on stack 
call c.ursh 
/ unsigned result on stack 


FUNCTION 
€.ursh shifts the unsigned val right by the integer count. If count is 
negative, a left shift occurs instead. 


RETURNS 
The value returned is the shifted unsigned result val>>count on the stack. 
All registers but af are preserved, and the arguments are popped off the 
stack. 


SEE ALSO 
c.ilsh, c.irsh 


count is blindly reduced modulo 256; no checking is performed for 
ridiculously long shifts (16, 128), which take a long time. 
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c.utd IV. Machine Support Library for 8080 


NAME 
e.utd - convert unsigned to double 


SYNOPSIS 
/ pointer to left on stack 
/ right on stack 
call c.utd 
/ pointer to left still on stack 


FONCTION 


c.utd 


c.utd is the internal routine called by C to convert the unsigned right 
into a double at left. It does so by extending the unsigned to an un- 
packed double fraction, then calling c.repk with a suitable charac- 
teristic. It does so without destroying any volatile registers, so the 


call can be used much as an ordinary machine instruction. 


RETURNS 


c.utd replaces the operand at left with the double representation of the 
unsigned right. All registers but af are preserved, and the right argu- 


ment is popped off the stack. 


SEE ALSO 
c.dti, c.itd, c.repk 
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9.utob IV. Machine Support Library for 8080 o.utob 


NAME 
c.utob - pack unsigned into bits 


SYNOPSIS 
/ pointer to bits on stack 
/ unsigned on stack 
/ offset/size on stack 
call c.utob 
rh Pointer to bits still on stack 


FUNCTION 
C.utob is the internal routine called by C to pack unsigned into the bit- 
field at bits. The field is specified by the two bytes offset/size, where 
the less significant byte offset is the number of places the bitfield must 
be snifted right to align it as an integer, and the more significant byte 
size is the number of bits in the field. offset is assumed to be in the 
range (0, 16), while size is in the range (0,16]. 


RETURNS 
c.utob inserts the unsigned into the specified bitfield at bits. All 
registers but af are preserved, and all arguments but the pointer to bits 
are popped off the stack. 


SEE ALSO 
¢.btou 
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0.zret IV. Machine Support Library for 8080 c.zret 


NAME 
C.zret - return from runtime compare function 


SYNOPSIS 
/ stack: be, hl, po, rignt, and left 
jnp c.zret 


FUNCTION 
C.zret is the code sequence used to return from several of the runtime 
compare functions. It assumes that the stack is setup as follows: 


8(sp) left operand 
6(sp) right operand 
4(sp) return link 
2(sp old hl 

O(sp) old bc 


It is assumed that f is set to reflect the comparison, and so must be 
preserved during the stack cleanup. 


RETURNS 
c.zret returns with the old bc and hl restored, both operands popped off 
the stack, and f unchanged from the jmp to c.zret. de is preserved, but 
the a register is undefined. 


SEE ALSO 
c.lret 
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in IV. Machine Support Library for 8080 in 


NAME 
in - input from port 


SYNOPSIS 
COUNT in(port) 
TEXT port; 


FUNCTION 
in is a C callable funotion to input a byte from an arbitrary port, which 
is specified by the less significant byte of port. To avoid modifying 
pure program text, in builds an instruction sequence on the stack and 
calls ít to input the byte. 


RETURNS 
in returns the byte read as an integer whose high byte is zero. 


SEE ALSO 
out 
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out IV. Machine Support Library for 8080 out 


NAME 
out - output to port 


SYNOPSIS 
VOID out(port, out) 
TEXT port, out; 


FUNCTION 
out is a C callable function to output a byte to an arbitrary port, which 
is specified by tne less significant byte of port. The data to be output 
is the less significant byte of out. To avoid modifying pure program 
text, out builds an instruction sequence on the stack and calls it to out- 
put the byte. 


Nothing. 


SEE ALSO 
in 
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